Analisar insights sobre a política da organização para projetos, pastas e organizações

Esta página mostra como gerenciar insights de políticas da organização, que são descobertas sobre a configuração e o uso de recursos. Os insights sobre a política da organização podem ajudar a identificar recursos que não são protegidos por políticas da organização.

Os insights sobre a política da organização às vezes são vinculados a recomendações de políticas da organização. As recomendações de políticas da organização sugerem ações que você pode realizar para corrigir os problemas identificados pelos insights de políticas da organização.

Antes de começar

Funções exigidas

Para receber as permissões necessárias para visualizar e modificar insights de políticas da organização, peça ao administrador para conceder a você o papel do IAM de Administrador de recomendações de políticas da organização (roles/recommender.orgPolicyAdmin) no recurso para o qual você quer gerenciar insights (projeto, pasta ou organização). Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esse papel predefinido contém as permissões necessárias para conferir e modificar os insights de políticas da organização. 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 conferir e modificar os insights da política da organização:

  • recommender.orgPolicyInsights.get
  • recommender.orgPolicyInsights.list
  • recommender.orgPolicyInsights.update

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

Listar insights de políticas da organização

Para listar todos os insights de política da organização do projeto, da pasta ou da organização, use um dos seguintes métodos:

gcloud

Use o comando gcloud recommender insights list para conferir todos os insights de política da organização do projeto, da pasta ou da organização.

Antes de executar o comando, substitua os seguintes valores:

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer listar insights. Use o valor project, folder ou organization.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização para o qual você quer listar insights. 
gcloud recommender insights list --insight-type=google.orgpolicy.policy.Insight \
    --RESOURCE_TYPE=RESOURCE_ID \
    --location=global

A saída lista todos os insights de política da organização para o projeto, a pasta ou a organização. Exemplo: 

INSIGHT_ID                            CATEGORY  INSIGHT_STATE  LAST_REFRESH_TIME     SEVERITY  INSIGHT_SUBTYPE                                          DESCRIPTION
66d543f3-845d-49d6-a26b-80d84804d8a8  SECURITY  ACTIVE         2024-12-10T08:00:00Z  HIGH      RESOURCE_VIOLATION_DISABLE_SERVICE_ACCOUNT_KEY_CREATION  Scanned 3 resources and found 0 violations for constraints/iam.managed.disableServiceAccountKeyCreation.

REST

O método insights.list da API Recommender lista todos os insights de política da organização para o projeto, a pasta ou a organização.

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

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer listar insights. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização para o qual você quer listar insights.
  • PROJECT_ID: o ID do projeto do 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/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights

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

A resposta lista todos os insights de política da organização para o projeto, a pasta ou a organização. Exemplo: 

[
  {
    "associatedRecommendations": [
      {
        "recommendation": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f"
      }
    ],
    "category": "SECURITY",
    "content": {
      "consolidatedPolicy": {
        "inheritFromParent": false,
        "name": "projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
        "policyRules": {
          "rules": [
            {
              "enforce": false
            }
          ]
        },
        "reset": false
      },
      "constraint": {
        "id": "constraints/iam.managed.disableServiceAccountKeyCreation",
        "name": "Disable service account key creation"
      },
      "evaluatedResources": [
        {
          "numOfResources": "2",
          "resourceType": "iam.googleapis.com/ServiceAccountKey"
        },
        {
          "numOfResources": "1",
          "resourceType": "cloudresourcemanager.googleapis.com/Project"
        }
      ],
      "violations": [
        {
          "numOfResources": "0",
          "resourceType": "iam.googleapis.com/ServiceAccountKey"
        },
        {
          "numOfResources": "0",
          "resourceType": "cloudresourcemanager.googleapis.com/Project"
        }
      ]
    },
    "description": "Scanned 3 resources and found 0 violations for constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"9a1ad019022f9f56\"",
    "insightSubtype": "RESOURCE_VIOLATION_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "lastRefreshTime": "2024-12-07T08:00:00Z",
    "name": "projects/123456789012/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/66d543f3-845d-49d6-a26b-80d84804d8a8",
    "observationPeriod": "86400s",
    "severity": "HIGH",
    "stateInfo": {
      "state": "ACTIVE",
      "stateMetadata": {
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }
]

Para saber mais sobre os componentes de um insight, consulte Analisar insights de política da organização nesta página.

Receber um insight de política da organização

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, da pasta ou da organização.
  • RESOURCE_TYPE: o tipo de recurso para o qual você quer gerenciar insights. Use o valor project, folder ou organization.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização para o qual você quer gerenciar insights. 
gcloud recommender insights describe INSIGHT_ID \
    --insight-type=google.orgpolicy.policy.Insight \
    --RESOURCE_TYPE=RESOURCE_ID \
    --location=global

A saída mostra os insights detalhados. Por exemplo, dois recursos são analisados em busca de chaves de conta de serviço externa, e nenhuma violação é detectada: 

associatedRecommendations:
- recommendation: projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f
category: SECURITY
content:
  consolidatedPolicy:
    inheritFromParent: false
    name: 'projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation'
    policyRules:
      rules: [
        "enforce": false
      ]
    reset: false
  constraint: {
    id: constraints/iam.managed.disableServiceAccountKeyCreation
    name: Disable service account key creation
  }
  evaluatedResources:
  - numOfResources: '1'
    resourceType: cloudresourcemanager.googleapis.com/Project
  - numOfResources: '2'
    resourceType: iam.googleapis.com/ServiceAccountKey
  violations:
  - numOfResources: '0'
    resourceType: iam.googleapis.com/ServiceAccountKey
  - numOfResources: '0'
    resourceType: cloudresourcemanager.googleapis.com/Project
description: Scanned 3 resources and found 0 violations for constraints/iam.managed.disableServiceAccountKeyCreation.
etag: '"34ddfdcefd214fd7"'
insightSubtype: RESOURCE_VIOLATION_DISABLE_SERVICE_ACCOUNT_KEY_CREATION
lastRefreshTime: '2024-12-10T08:00:00Z'
name: projects/123456789012/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/66d543f3-845d-49d6-a26b-80d84804d8a8
observationPeriod: 86400s
severity: HIGH
stateInfo:
  state: ACTIVE
targetResources:
- //cloudresourcemanager.googleapis.com/projects/123456789012

Para saber mais sobre os componentes de um insight, consulte Analisar insights de política da organização 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:

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer gerenciar insights. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização para o qual você quer gerenciar insights.
  • INSIGHT_ID: o ID do insight que você quer ver. Se você não souber o ID do insight, poderá encontrá-lo listando os insights no projeto, na pasta ou na organização. O ID de um insight é tudo o que aparece depois de insights/ no campo name do insight.
  • PROJECT_ID: o ID do projeto do 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/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/INSIGHT_ID

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

A resposta contém o insight. Por exemplo, dois recursos são analisados para chaves de conta de serviço externa, e nenhuma violação é detectada: 

[
  {
    "associatedRecommendations": [
      {
        "recommendation": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f"
      }
    ],
    "category": "SECURITY",
    "content": {
      "consolidatedPolicy": {
        "inheritFromParent": false,
        "name": "projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
        "policyRules": {
          "rules": [
            {
              "enforce": false
            }
          ]
        },
        "reset": false
      },
      "constraint": {
        "id": "constraints/iam.managed.disableServiceAccountKeyCreation",
        "name": "Disable service account key creation"
      },
      "evaluatedResources": [
        {
          "numOfResources": "1",
          "resourceType": "cloudresourcemanager.googleapis.com/Project"
        },
        {
          "numOfResources": "2",
          "resourceType": "iam.googleapis.com/ServiceAccountKey"
        }
      ],
      "violations": [
        {
          "numOfResources": "0",
          "resourceType": "iam.googleapis.com/ServiceAccountKey"
        },
        {
          "numOfResources": "0",
          "resourceType": "cloudresourcemanager.googleapis.com/Project"
        }
      ]
    },
    "description": "Scanned 2 resources and found 0 violations for constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"9a1ad019022f9f56\"",
    "insightSubtype": "RESOURCE_VIOLATION_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "lastRefreshTime": "2024-12-03T08:00:00Z",
    "name": "projects/123456789012/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/66d543f3-845d-49d6-a26b-80d84804d8a8",
    "observationPeriod": "86400s",
    "severity": "HIGH",
    "stateInfo": {
      "state": "ACTIVE",
      "stateMetadata": {
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }
]

Para saber mais sobre os componentes de um insight, consulte Analisar insights de política da organização nesta página.

Analisar insights de políticas da organização

Depois de receber um único insight, é possível analisar o conteúdo para entender a configuração da política da organização nos seus recursos, incluindo violações.

Os insights de políticas da organização (google.orgpolicy.policy.Insight) 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 vai estar vazio.
  • category: a categoria dos insights de políticas da organização é sempre SECURITY.
  • content: fornece detalhes sobre os recursos e a política da organização que foram analisados. Este campo contém os seguintes componentes:
    • constraint: a restrição que foi analisada.
    • consolidatedPolicy: a política da organização para o recurso analisado.
    • evaluatedResources: os recursos que foram avaliados para gerar o insight.
    • violations: o número e os tipos de recursos que violam a política da organização.
  • 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 realizada 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:

    RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/INSIGHT_ID

    Os marcadores têm os seguintes valores:

    • RESOURCE_TYPE: o tipo de recurso para o qual o insight foi gerado.
    • RESOURCE_ID: o ID do projeto, da pasta ou da organização em que o insight foi gerado.
    • 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.
  • severity: a gravidade do insight. Os insights das políticas da organização têm uma gravidade de HIGH.

  • 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 um insight está no estado 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, da pasta ou da organização relacionado ao insight. Por exemplo, //cloudresourcemanager.googleapis.com/projects/1234567890.

Marcar um insight de política da organização 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, da pasta ou da organização.
  • RESOURCE_TYPE: o tipo de recurso para o qual você quer gerenciar insights. Use o valor project, folder ou organization.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização para o qual você quer gerenciar insights.

  • 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.orgpolicy.policy.Insight \
    --RESOURCE_TYPE=RESOURCE_ID \
    --location=global \
    --etag=ETAG

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

associatedRecommendations:
- recommendation: folders/234567890123/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f
category: SECURITY
content:
  consolidatedPolicy:
    inheritFromParent: false
    name: 'projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation'
    policyRules:
      rules: [
        "enforce": false
      ]
    reset: false
  constraint: {
    id: constraints/iam.managed.disableServiceAccountKeyCreation
    name: Disable service account key creation
  }
  evaluatedResources:
  - numOfResources: '0'
    resourceType: iam.googleapis.com/ServiceAccountKey
  - numOfResources: '1'
    resourceType: cloudresourcemanager.googleapis.com/Folder
  - numOfResources: '1'
    resourceType: cloudresourcemanager.googleapis.com/Project
  violations:
  - numOfResources: '0'
    resourceType: iam.googleapis.com/ServiceAccountKey
  - numOfResources: '0'
    resourceType: cloudresourcemanager.googleapis.com/Folder
  - numOfResources: '0'
    resourceType: cloudresourcemanager.googleapis.com/Project
description: Scanned 2 resources and found 0 violations for constraints/iam.managed.disableServiceAccountKeyUpload.
etag: '"2cbb89b22fe2dab7"'
insightSubtype: RESOURCE_VIOLATION_DISABLE_SERVICE_ACCOUNT_KEY_UPLOAD
lastRefreshTime: '2024-12-10T08:00:00Z'
name: folders/234567890123/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/66d543f3-845d-49d6-a26b-80d84804d8a8
observationPeriod: 86400s
severity: HIGH
stateInfo:
  state: ACCEPTED
targetResources:
- //cloudresourcemanager.googleapis.com/folders/234567890123

Para saber mais sobre as informações de estado de um insight, consulte Analisar insights de política da organização 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:

  • RESOURCE_TYPE: o tipo de recurso para o qual você quer gerenciar insights. Use o valor projects, folders ou organizations.
  • RESOURCE_ID: o ID do projeto, da pasta ou da organização para o qual você quer gerenciar insights.
  • INSIGHT_ID: o ID do insight que você quer ver. Se você não souber o ID do insight, poderá encontrá-lo listando os insights no projeto, na pasta ou na organização. 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.
  • PROJECT_ID: o ID do projeto do Google Cloud . Os IDs do projeto são strings alfanuméricas, como my-project.

Método HTTP e URL: 

POST https://recommender.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/locations/global/insightTypes/google.orgpolicy.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: 

[
  {
    "associatedRecommendations": [
      {
        "recommendation": "projects/123456789012/locations/global/recommenders/google.orgpolicy.policy.Recommender/recommendations/fb927dc1-9695-4436-0000-f0f285007c0f"
      }
    ],
    "category": "SECURITY",
    "content": {
      "consolidatedPolicy": {
        "inheritFromParent": false,
        "name": "projects/123456789012/policies/iam.managed.disableServiceAccountKeyCreation",
        "policyRules": {
          "rules": [
            {
              "enforce": false
            }
          ]
        },
        "reset": false
      },
      "constraint": {
        "id": "constraints/iam.managed.disableServiceAccountKeyCreation",
        "name": "Disable service account key creation"
      },
      "evaluatedResources": [
        {
          "numOfResources": "1",
          "resourceType": "cloudresourcemanager.googleapis.com/Project"
        },
        {
          "numOfResources": "2",
          "resourceType": "iam.googleapis.com/ServiceAccountKey"
        }
      ],
      "violations": [
        {
          "numOfResources": "0",
          "resourceType": "iam.googleapis.com/ServiceAccountKey"
        },
        {
          "numOfResources": "0",
          "resourceType": "cloudresourcemanager.googleapis.com/Project"
        }
      ]
    },
    "description": "Scanned 2 resources and found 0 violations for constraints/iam.managed.disableServiceAccountKeyCreation.",
    "etag": "\"9a1ad019022f9f56\"",
    "insightSubtype": "RESOURCE_VIOLATION_DISABLE_SERVICE_ACCOUNT_KEY_CREATION",
    "lastRefreshTime": "2024-12-03T08:00:00Z",
    "name": "projects/123456789012/locations/global/insightTypes/google.orgpolicy.policy.Insight/insights/66d543f3-845d-49d6-a26b-80d84804d8a8",
    "observationPeriod": "86400s",
    "severity": "HIGH",
    "stateInfo": {
      "state": "ACCEPTED",
      "stateMetadata": {
        "reviewedBy": "alice",
        "priority": "high"
      }
    },
    "targetResources": [
      "//cloudresourcemanager.googleapis.com/projects/123456789012"
    ]
  }
]

Para saber mais sobre as informações de estado de um insight, consulte Analisar insights de política da organização nesta página.

A seguir