Como gerenciar insights

Além de fazer recomendações, o Recomendador usa machine learning (ML) para apresentar insights detalhados. Os insights são descobertas que destacam padrões notáveis no uso de recursos. Por exemplo, é possível coletar mais informações sobre o uso de permissões no seu projeto ou identificar contas de serviço não utilizadas. Alguns insights também estão vinculados às recomendações porque são evidências delas.

O gerenciamento de identidade e acesso (IAM) oferece os seguintes tipos de insights:

  • Insights de política: descobertas baseadas em ML sobre o uso de permissões no projeto.
  • Insights de conta de serviço: descobertas sobre contas de serviço no projeto, como as contas que não foram usadas nos últimos 90 dias.

Antes de começar

Permissões necessárias

As permissões necessárias para usar os insights variam de acordo com o que você quer fazer.

Permissões para ver insights

Para ver os insights, você precisa de um papel que inclua as seguintes permissões, em que insight-type é iamPolicyInsights ou iamServiceAccountInsights:

  • recommender.insight-type.get
  • recommender.insight-type.list

Para ter essas permissões seguindo o princípio do privilégio mínimo, peça ao administrador para conceder a você um dos seguintes papéis:

  • Leitor do recomendador do IAM (roles/recommender.iamViewer)
  • Revisor de segurança do IAM (roles/iam.securityReviewer)

Como alternativa, o administrador pode conceder a você um papel diferente que inclua as permissões necessárias, como um papel personalizado ou um papel predefinido mais permissivo.

Permissões para modificar insights

Para modificar os insights, você precisa de um papel que inclua as seguintes permissões, em que insight-type é iamPolicyInsights ou iamServiceAccountInsights:

  • recommender.insight-type.get
  • recommender.insight-type.list
  • recommender.insight-type.update

Para receber essas permissões seguindo o princípio do privilégio mínimo, peça ao administrador que conceda a você o papel de administrador do recomendador do IAM (roles/recommender.iamAdmin).

Como alternativa, o administrador pode conceder a você um papel diferente que inclua as permissões necessárias, como um papel personalizado ou um papel predefinido mais permissivo.

Como listar insights

Para listar todos os insights de um tipo específico ao seu projeto, use um dos seguintes métodos:

gcloud

Use o comando gcloud recommender insights list para ver todos os insights de um tipo específico ao seu projeto.

Substitua insight-type-id pelo tipo de insight que você quer listar. Use google.iam.policy.Insight para ver insights de política e google.iam.serviceAccount.Insight para ver insights de conta de serviço.

gcloud recommender insights list --insight-type=insight-type-id \
    --location=global

A saída lista todos os insights de um tipo específico ao seu projeto. Por exemplo, listar todos os insights de política do projeto gera um resultado como o seguinte:

INSIGHT_ID                            LOCATION  INSIGHT_TYPE               CATEGORY  INSIGHT_STATE  LAST_REFRESH_TIME
07841f74-02ce-4de8-bbe6-fc4eabb68568  global    google.iam.policy.Insight  SECURITY  ACCEPTED       2020-07-12T07:00:00Z
0d3ce433-f067-4e78-b6ae-03d7d1f6f040  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
0e2cc488-38fb-4b9b-942c-cfe06a0ab88f  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
12b557be-d48f-49cf-a0b0-b3b73a178edf  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
279ef748-408f-44db-9a4a-1ff8865b9839  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
29a4553d-9ffb-4508-9f13-77f40fc4e8b6  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
2a00a91a-3e37-4dca-81f7-fb607d18053f  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
2baea818-df89-4ab3-8a48-0e752459d816  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
4a59da9d-cde8-46cc-9c68-6980487175fb  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z
78fee8d9-c25c-4070-9f1b-ae5e4a4a164b  global    google.iam.policy.Insight  SECURITY  ACTIVE         2020-07-13T07:00:00Z

REST

O método insights.list da API Recommender lista todos os insights de um tipo específico ao seu projeto.

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

  • project-id: o ID do projeto do Google Cloud.
  • insight-type-id: o tipo de insight que você quer listar. Para insights de política, use google.iam.policy.Insight. Para insights de conta de serviço, use google.iam.serviceAccount.Insight.

Método HTTP e URL: 

GET https://recommender.googleapis.com/v1/projects/project-id/locations/global/insightTypes/insight-type-id/insights

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

A resposta lista todos os insights de um tipo específico no projeto. Por exemplo, ela pode listar todos os insights de política no projeto: 

{
  "insights": [
    {
      "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
      "description": "0 permission checks were authorized by this policy binding tuple.",
      "content": {
        "role": "roles/viewer",
        "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [],
        "inferredPermissions": []
      },
      "lastRefreshTime": "2020-07-12T07:00:00Z",
      "observationPeriod": "7776000s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
        }
      ],
      "targetResources": [
        "//cloudresourcemanager.googleapis.com/projects/1234567890"
      ],
      "insightSubtype": "PERMISSIONS_USAGE",
      "etag": "\"b153ab487e4ae100\""
    },
    {
      "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/f4292f55-105b-4744-9dc3-fcacf59685bb",
      "description": "4 permission checks were authorized by this policy binding tuple.",
      "content": {
        "role": "roles/owner",
        "member": "serviceAccount:my-service-account2@my-project.iam.gserviceaccount.com",
        "condition": {
          "expression": "",
          "title": "",
          "description": "",
          "location": ""
        },
        "exercisedPermissions": [
          {
            "permission": "iam.roles.create"
          },
          {
            "permission": "iam.roles.delete"
          },
          {
            "permission": "iam.roles.list"
          },
          {
            "permission": "iam.roles.update"
          }
        ],
        "inferredPermissions": []
      },
      "lastRefreshTime": "2020-07-12T07:00:00Z",
      "observationPeriod": "7776000s",
      "stateInfo": {
        "state": "ACTIVE"
      },
      "category": "SECURITY",
      "associatedRecommendations": [
        {
          "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/6ab16c1d-edce-45e5-8d82-570fdd49892a"
        }
      ],
      "targetResources": [
        "//cloudresourcemanager.googleapis.com/projects/1234567890"
      ],
      "insightSubtype": "PERMISSIONS_USAGE",
      "etag": "\"49bb705553338fc3\""
    }
  ]
}

Para saber mais sobre os componentes de um insight, consulte Como analisar insights nesta página.

Como receber um único insight

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 do IAM.

Antes de usar esta amostra, faça as substituições a seguir:

  • insight-id: o ID do insight que você quer ver. Para encontrar o ID, liste os insights no projeto.

  • insight-type-id: o tipo de insight que você quer ver. Use google.iam.policy.Insight para ver insights de política e google.iam.serviceAccount.Insight para ver insights de conta de serviço.

gcloud recommender insights describe insight-id \
    --insight-type=insight-type-id --location=global

A saída mostra os insights detalhados. Por exemplo, o insight a seguir indica que my-service-account@my-project.iam.gserviceaccount.com não usou permissões do papel Leitor (roles/viewer) nos últimos 90 dias:

associatedRecommendations:
- recommendation: projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  exercisedPermissions: []
  inferredPermissions: []
  member: serviceAccount:my-service-account@my-project.iam.gserviceaccount.com
  role: roles/viewer
description: 0 permission checks were authorized by this policy binding tuple.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
  state: ACTIVE
targetResources:
- //cloudresourcemanager.googleapis.com/projects/1234567890

Para saber mais sobre os componentes de um insight, consulte Como analisar insights nesta página.

REST

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

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

  • project-id: o ID do projeto do Google Cloud.
  • insight-type-id: o tipo de insight que você quer ver. Para insights de política, use google.iam.policy.Insight. Para insights de conta de serviço, use google.iam.serviceAccount.Insight.
  • insight-id: o ID do insight que você quer ver. Para encontrar o ID, liste os insights no seu 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/global/insightTypes/insight-type-id/insights/insight-id

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

A resposta contém o insight. Exemplo: 

{
  "name": "projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "content": {
    "role": "roles/viewer",
    "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": []
  },
  "lastRefreshTime": "2020-07-12T07:00:00Z",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACTIVE"
  },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
    }
  ],
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/1234567890"
  ],
  "insightSubtype": "PERMISSIONS_USAGE",
  "etag": "\"b153ab487e4ae100\""
}

Para saber mais sobre os componentes de um insight, consulte Como analisar insights nesta página.

Como analisar insights

Os insights são divididos em tipos e subtipos. Os tipos de insight informam o tipo de recurso dele. Os subtipos de insight informam o tipo de informações que os insights contêm.

O IAM oferece os seguintes tipos e subtipos de insight:

Tipo de insight Subtipo de insight
Insights de política PERMISSION_USAGE: descobertas baseadas em ML sobre o uso de permissões no projeto.
Insights de conta de serviço SERVICE_ACCOUNT_USAGE: descobertas sobre as contas de serviço no projeto que não foram usadas nos últimos 90 dias.

O conteúdo do insight é determinado pelo subtipo dele. Os subtipos de insight listados na tabela anterior têm os seguintes componentes:

  • 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 dos insights PERMISSION_USAGE e SERVICE_ACCOUNT_USAGE é sempre SECURITY.

  • content: as informações no campo content são determinadas pelo subtipo de insight:

    Subtipo de insight Conteúdo
    PERMISSION_USAGE

    Relata o uso das permissões de um membro referentes a um papel específico. Este campo contém os seguintes componentes:

    • member: o membro com o uso analisado das permissões.
    • role: o papel com o uso analisado das permissões.
    • condition: qualquer condição anexada à vinculação que concede o papel ao membro. Se não houver condições, esse campo conterá uma condição vazia.
    • exercisedPermissions: as permissões do papel que o membro usou durante o período de observação.
    • inferredPermissions: as permissões do papel que o recomendador do IAM determinou por ML e que o membro provavelmente precisará com base nas permissões que ele usou.
    SERVICE_ACCOUNT_USAGE

    Relata a última vez que a conta de serviço foi autenticada. Este campo contém os seguintes componentes:

    • serviceAccountId: o ID numérico exclusivo da conta de serviço.
    • email: o endereço de e-mail da conta de serviço.
    • lastAuthenticatedTime: o horário mais recente em que a conta de serviço foi autenticada. Se a conta de serviço não tem autenticações registradas, esse campo não é incluído.

  • description: um resumo legível do insight.

  • etag: uma impressão digital exclusiva que identifica o estado atual de um insight. Sempre que o insight é alterado, um novo valor de ETag é atribuído.

    Para alterar o estado de um insight, informe a ETag do insight atual. O uso de ETags 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, que é PERMISSION_USAGE ou SERVICE_ACCOUNT_USAGE.

  • 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/global/insightTypes/insight-type-id/insights/insight-id

    Os marcadores têm os seguintes valores:

    • project-id: o ID do projeto em que o insight foi gerado.
    • insight-type-id: o tipo do insight. Os insights de política têm o tipo google.iam.policy.Insight. Os insights de conta de serviço têm o tipo google.iam.serviceAccount.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 projeto do Google Cloud relacionado ao insight. Por exemplo, //cloudresourcemanager.googleapis.com/projects/1234567890

Como marcar um insight 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 suas 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 seu insight para marcar um insight como ACCEPTED.

Antes de usar o comando de amostra, substitua os seguintes valores:

  • insight-id: o ID do insight que você quer marcar como ACCEPTED. Para encontrar o ID, liste os insights no projeto.

  • insight-type-id: o tipo de insight que você quer marcar como ACCEPTED. Para insights de política, use google.iam.policy.Insight. Para insights de conta de serviço, use google.iam.serviceAccount.Insight.

  • 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 etag da saída, incluindo as aspas delimitadoras. Por exemplo, "d3cdec23cc712bd0".
gcloud recommender insights mark-accepted insight-id \
    --insight-type=insight-type-id --location=global \
    --etag=etag

A saída mostra o insight, agora com o estado ACCEPTED:

associatedRecommendations:
- recommendation: projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/0573b702-96a5-4622-a916-c762e7b0731f
category: SECURITY
content:
  condition:
    description: ''
    expression: ''
    location: ''
    title: ''
  exercisedPermissions: []
  inferredPermissions: []
  member: serviceAccount:my-service-account@my-project.iam.gserviceaccount.com
  role: roles/viewer
description: 0 permission checks were authorized by this policy binding tuple.
etag: '"d3cdec23cc712bd0"'
insightSubtype: PERMISSIONS_USAGE
lastRefreshTime: '2020-07-11T07:00:00Z'
name: projects/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/0d3ce433-f067-4e78-b6ae-03d7d1f6f040
observationPeriod: 7776000s
stateInfo:
  state: ACCEPTED
targetResources:
- //cloudresourcemanager.googleapis.com/projects/1234567890

Para saber mais sobre as informações de estado de um insight, consulte Como analisar insights 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 abaixo, faça as substituições a seguir:

  • project-id: o ID do projeto do Google Cloud.
  • insight-type-id: o tipo de insight que você quer marcar como ACCEPTED. Para insights de política, use google.iam.policy.Insight. Para insights de conta de serviço, use google.iam.serviceAccount.Insight.
  • insight-id: o ID do insight que você quer marcar como ACCEPTED. Para encontrar o ID, liste os insights no seu projeto. O ID de um insight é tudo o que aparece depois de insights/ no campo name do insight.
  • etag: um 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/global/insightTypes/insight-type-id/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/1234567890/locations/global/insightTypes/google.iam.policy.Insight/insights/07841f74-02ce-4de8-bbe6-fc4eabb68568",
  "description": "0 permission checks were authorized by this policy binding tuple.",
  "content": {
    "role": "roles/viewer",
    "member": "serviceAccount:my-service-account@my-project.iam.gserviceaccount.com",
    "condition": {
      "expression": "",
      "title": "",
      "description": "",
      "location": ""
    },
    "exercisedPermissions": [],
    "inferredPermissions": []
  },
  "lastRefreshTime": "2020-07-12T07:00:00Z",
  "observationPeriod": "7776000s",
  "stateInfo": {
    "state": "ACCEPTED"
    },
  "category": "SECURITY",
  "associatedRecommendations": [
    {
      "recommendation": "projects/1234567890/locations/global/recommenders/google.iam.policy.Recommender/recommendations/b1932220-867d-43d1-bd74-fb95876ab656"
    }
  ],
  "targetResources": [
    "//cloudresourcemanager.googleapis.com/projects/1234567890"
  ],
  "insightSubtype": "PERMISSIONS_USAGE",
  "etag": "\"b153ab487e4ae100\""
}

Para saber mais sobre as informações de estado de um insight, consulte Como analisar insights nesta página.

A seguir