Políticas de inspeção

Este tópico descreve como inspecionar ou validar políticas de permissão do Identity and Access Management (IAM).

Antes de começar

Funções exigidas

Para inspecionar a política de permissão de um recurso, você precisa de permissões para acessar o recurso e receber e definir a política de permissão para o recurso. Essas permissões têm o seguinte formato, em que SERVICE é o nome do serviço que possui o recurso e RESOURCE_TYPE é o nome do tipo de recurso para que você quer gerenciar o acesso:

  • SERVICE.RESOURCE_TYPE.get
  • SERVICE.RESOURCE_TYPE.getIamPolicy
  • SERVICE.RESOURCE_TYPE.setIamPolicy

Por exemplo, para inspecionar uma política de permissão de um projeto, você precisa das seguintes permissões:

  • resourcemanager.projects.get
  • resourcemanager.projects.getIamPolicy
  • resourcemanager.projects.setIamPolicy

Para receber as permissões necessárias, peça ao administrador para conceder a você um papel predefinido ou personalizado que inclua as permissões. Por exemplo, o administrador pode conceder a você o papel de Administrador de segurança (roles/iam.securityAdmin), que inclui permissões para receber quase todos os recursos do Google Cloud e gerenciar as políticas de permissão.

Entendendo a inspeção para políticas de permissão

No contexto das políticas de permissão, inspecionar é um método de examinar uma política de permissão nova ou existente e de verificar problemas específicos. Esses problemas incluem as seguintes possibilidades:

  • Sugestões
  • Avisos
  • Informações que podem ajudar a melhorar a intenção da política de permissão, como melhor sintaxe e semântica
  • Erros de sintaxe ou de semântica que causam falha nas operações de setIamPolicy

Se você tentar atualizar uma política de permissão e encontrar um erro, a inspeção da política de permissão poderá ajudar a encontrar a causa do erro. Também é possível usar a inspeção para garantir que uma vinculação de papel condicional tenha o efeito pretendido.

Como inspecionar uma condição

As expressões de condição podem ser complexas, especialmente em cenários que exigem várias cláusulas e operadores lógicos para gerenciar o acesso de forma adequada. Se uma expressão de condição contiver uma lógica inválida, ou se a sintaxe violar as restrições de uma expressão de condição, não será possível adicionar a condição a uma política de permissão.

Além disso, mesmo que uma expressão de condição use a sintaxe correta, ela pode conter erros semânticos, o que pode impedir o funcionamento esperado das políticas de permissão e vinculações de papéis. Erros semânticos comuns incluem:

  • Uso de funções não recomendadas
  • Uso de tipos de recursos legados ou nomes de serviços legados
  • Condições ineficazes, como um intervalo de data ou hora não aplicável

Ao inspecionar uma condição, o lint verifica a expressão condicional e relata os erros de sintaxe. Ele também informa possíveis erros semânticos que podem causar resultados inesperados.

Antes de tentar configurar uma nova vinculação condicional de papel, é recomendável inspecionar a expressão primeiro. Esta seção mostra como inspecionar uma expressão de condição usando o Console do Google Cloud, a Google Cloud CLI ou a API REST.

Para inspecionar uma expressão de condição:

Console

  1. No Console do Google Cloud, abra a página IAM.

    Acessar IAM

  2. Clique em Selecionar um projeto e em Abrir.

  3. Na lista de participantes, localize o participante desejado e clique no botão Editar .

  4. No painel Editar permissões, localize o papel desejado que você quer inspecionar. Em seguida, em Condição do IAM (opcional), clique no nome da condição.

  5. Em Editor de condições, adicione ou edite manualmente uma expressão de condição.

  6. Para validar a sintaxe CEL, clique em Executar lint.

    Se a sintaxe tiver erros, um ícone Erro será exibido ao lado da linha incorreta. Para ver detalhes sobre cada erro, mantenha o ponteiro do mouse sobre o ícone.

    Se a condição usar a sintaxe correta, mas o lint encontrar um possível problema, um ícone de Aviso será exibido ao lado da linha com o problema. Para ver detalhes sobre cada aviso, mantenha o ponteiro do mouse sobre o ícone.

  7. Faça as alterações necessárias na expressão de condição. Depois de clicar em Executar lint, ele será executado automaticamente em segundo plano enquanto você edita a expressão.

    Corrija todos os erros antes de salvar a expressão de condição. Também recomendamos corrigir todos os avisos.

  8. Quando não houver erros ou avisos, clique em Salvar para aplicar a condição.

  9. Quando o painel Editar condição for fechado, clique em Salvar novamente no painel Editar permissões para atualizar a política do IAM.

gcloud

Execute o comando gcloud alpha iam policies lint-condition para inspecionar uma determinada expressão de condição. Para executá-lo, crie um arquivo de texto que contenha a condição ou especifique as sinalizações para o título, a descrição e a expressão da condição.

O exemplo a seguir usa um arquivo de texto que contém a seguinte condição:

condition.json

{
  "title": "1_less_than_2",
  "description": "",
  "expression": "1 <"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

A saída do comando contém o seguinte:

lintResults:
- debugMessage: |-
    ERROR: Parse expression:1:3: mismatched input '<EOF>' expecting {'[', '{', '(', '.', '-', '!', 'true', 'false', 'null', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}
      | 1 >
      | ...^
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 3
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionCompileCheck
...

Cada um dos resultados da inspeção contém um debugMessage que pode ser usado para ajudar a localizar o problema com a expressão de condição. Se a compilação da condição falhar, você verá vários tipos diferentes de validationUnitName com o seguinte texto de debugMessage:

The validation unit is skipped due to absence of a required object: CheckedExpr

Faça alterações para que a expressão seja compilada e inspecione a condição novamente.

REST

O iamPolicies.lintPolicy método inspeciona ou valida, uma expressão de condição em uma política de permissão.

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

  • condition: um objeto Expr que representa a condição a ser inspecionada. Por exemplo: 

    "title": "1_less_than_2",
"description": "",
"expression": "1 <"

    Para saber mais sobre o formato de um objeto Expr, consulte a referência do esquema Expr.

Método HTTP e URL:

POST https://iam.googleapis.com/v1/iamPolicies:lintPolicy

Corpo JSON da solicitação:

{
  "condition": {
    condition
  }
}

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

O corpo da resposta contém um ou mais objetos LintResult, como estes: 

{
  "lint_results": {
    "level": "CONDITION",
    "validation_unit_name": "LintValidationUnits/ConditionCompileCheck",
    "severity": "ERROR",
    "field_name": "condition.expression",
    "location_offset": "2",
    "debug_message": "ERROR: Parse expression:1:2: mismatched input \'<EOF>\' expecting {\'[\', \'{\', \'(\', \'.\', \'-\', \'!\', \'true\', \'false\', \'null\', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}\n  | 1<\n  | ..^"
  },
  "lint_results": {
    "level": "CONDITION",
    "validation_unit_name": "LintValidationUnits/ConditionComplexityCheck",
    "severity": "NOTICE",
    "field_name": "condition.expression",
    "debug_message": "The validation unit is skipped due to absence of a required object: CheckedExpr"
  }
}

Cada um dos resultados da inspeção contém um debug_message que pode ser usado para ajudar a localizar o problema com a expressão de condição. Se a compilação da condição falhar, você verá vários tipos diferentes de validation_unit_name com o seguinte texto de debugMessage:

The validation unit is skipped due to absence of a required object: CheckedExpr

Faça alterações para que a expressão seja compilada e inspecione a condição novamente.

Unidades de validação compatíveis

Conforme descrito anteriormente, uma unidade de validação é um tipo de inspeção individual que avalia se a expressão tem problemas sintáticos. A tabela abaixo resume as unidades de validação compatíveis, cada uma com o nível de inspeção desejado, a gravidade do resultado da inspeção e uma breve descrição.

Unidade de validação Nível de inspeção Gravidade Descrição
ConditionCompileCheck CONDITION ERROR A expressão da condição tem um erro de compilação como resultado de uma sintaxe CEL inválida.
ConditionComplexityCheck CONDITION ERROR A expressão da condição contém mais do que o máximo de 12 operadores lógicos.
DateTimeCheck CONDITION WARNING

A expressão condicional especifica uma comparação de carimbo de data/hora que sempre faz uma avaliação de verdadeiro ou falso devido a um destes problemas:

DateTimeRangeCheck CONDITION WARNING Valor fora do intervalo da função avançada do carimbo de data/hora pretendido e da expressão de comparação. Veja os valores válidos para funções avançadas de carimbo de data/hora.
DrgGetAttributeDefaultValueCheck CONDITION ERROR A expressão de condição chama api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', V), em que V é qualquer valor diferente de uma lista vazia, []. Para este atributo da API, V precisa ser sempre uma lista vazia.
EffectiveTimeRangeCheck CONDITION WARNING Em um uso mais complexo de funções e comparação de carimbo de data/hora, a expressão resulta em um intervalo de tempo efetivo vazio e, portanto, é efetivamente falso. Ou ainda, o intervalo de tempo abrange um intervalo completo e, assim, é efetivamente verdadeiro.
HasOnlyListConstCheck CONDITION ERROR A expressão de condição chama hasOnly(List<T>), em que o tipo T não é constante, como uma string ou um número inteiro. A função hasOnly() aceita apenas uma lista de constantes.
HasOnlyListLengthCheck CONDITION ERROR A expressão de condição chama hasOnly(List<T>), e List<T> contém mais do que o máximo de 10 elementos.
ResourceServiceLiteralCheck CONDITION WARNING O valor resource.service especificado não é compatível. A expressão que usa esse literal de string para comparação de igualdade é efetivamente falsa. Use um valor compatível.
ResourceTypeLiteralCheck CONDITION WARNING O valor resource.type especificado não é compatível. A expressão que usa esse literal de string para comparação de igualdade é efetivamente falsa. Use um valor compatível.
RestrictedAttributesCheck CONDITION WARNING A expressão usa um atributo que está restrito ou não é compatível. A definição da expressão condicional pode não ter êxito. Consulte a lista de atributos.

Exemplos de inspeção

Esta seção mostra exemplos de condições que fazem com que cada unidade de validação relate problemas. Cada exemplo demonstra a inspeção usando a CLI do Google Cloud.

Nenhum problema de validação

Exemplo de condição:

{
  "title": "1_less_than_2",
  "description": "",
  "expression": "1 < 2"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

{}

ConditionCompileCheck

Exemplo de condição:

{
  "title": "Condition not compiling",
  "description": "",
  "expression": "true=false"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: |-
    ERROR: Parse expression:1:4: token recognition error at: '=f'
      | true=false
      | ....^
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 4
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionCompileCheck

ConditionComplexityCheck

Exemplo de condição:

{
  "title": "Condition not compiling",
  "description": "",
  "expression":
    "1<2 || 2<3 || 3<4 || 4<5 || 5<6 || 6<7 || 7<8 || 8<9 || 9<10 || 10<11 || 11<12 || 12<13 || 13<14 || 14<15"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: Logical operators count must not be more than 12
  fieldName: condition.expression
  level: CONDITION
  severity: ERROR
  validationUnitName: LintValidationUnits/ConditionComplexityCheck

DateTimeCheck

Exemplo de condição:

{
  "title": "Condition not compiling",
  "description": "",
  "expression": "request.time < timestamp('2000-01-01T00:00:00Z')"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: Ineffective date time value 2000-01-01T00:00:00+00:00 parsed
    from "2000-01-01T00:00:00Z"; condition is effectively False. Time expired
    already.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 25
  severity: WARNING
  validationUnitName: LintValidationUnits/DateTimeCheck

DateTimeRangeCheck

Exemplo de condição:

{
  "title": "Time function out of range",
  "description": "",
  "expression": "request.time.getMonth() > 13"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: The value being compared to the specified timestamp function
    (getMonth) must be in range [0, 11].
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 26
  severity: WARNING
  validationUnitName: LintValidationUnits/DateTimeRangeCheck

DrgGetAttributeDefaultValueCheck

Exemplo de condição:

{
  "title": "DRG condition takes non empty list as default value",
  "description": "",
  "expression":
    "api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', ['roles/viewer']).hasOnly(['roles/editor'])"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: api.getAttribute call on
    'iam.googleapis.com/modifiedGrantsByRole' can only
    accept empty list ('[]') as default value.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 60
  severity: ERROR
  validationUnitName: LintValidationUnits/DrgGetAttributeDefaultValueCheck

EffectiveTimeRangeCheck

Exemplo de condição:

{
  "title": "Empty time range",
  "description": "",
  "expression": "request.time.getMonth() > 5 && request.time.getMonth() < 4"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: The aggregate of time functions [getMonth] results in empty ranges.
  fieldName: condition.expression
  level: CONDITION
  severity: WARNING
  validationUnitName: LintValidationUnits/EffectiveTimeRangeCheck

HasOnlyListConstCheck

Exemplo de condição:

{
  "title": "hasOnly contains more than constant value",
  "description": "",
  "expression":
    "api.getAttribute('somekey', []).hasOnly(['somevalue', resource.name])"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: hasOnly() expects an argument of type list containing only const
      values, but a non-const expression was found in the list.
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 59
  severity: ERROR
  validationUnitName: LintValidationUnits/HasOnlyListConstCheck

HasOnlyListLengthCheck

Exemplo de condição:

{
  "title": "hasOnly contains more than 10 elements",
  "description": "",
  "expression":
    "api.getAttribute('somekey', []).hasOnly([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: The list argument to hasOnly() cannot have more than 10 elements
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 39
  severity: ERROR
  validationUnitName: LintValidationUnits/HasOnlyListLengthCheck

ResourceServiceLiteralCheck

Exemplo de condição:

{
  "title": "Condition with unsupported resource service string",
  "description": "",
  "expression": "resource.service == 'resourcemanager'"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: 'resource.service : resourcemanager is not supported. Using this
    value in condition may lead to unintended consequences. Check user guide at
    https://cloud.google.com/iam/docs/conditions-resource-attributes#resource_service_values
    for supported values for resource.service.'
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 20
  severity: WARNING
  validationUnitName: LintValidationUnits/ResourceServiceLiteralCheck

ResourceTypeLiteralCheck

Exemplo de condição:

{
  "title": "Condition with legacy resource type",
  "description": "",
  "expression": "resource.type == 'resourcemanager.projects'"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: 'resource.type : resourcemanager.projects is not supported.
    Using this value in condition may lead to unintended consequences. Check
    user guide at https://cloud.google.com/iam/docs/conditions-resource-attributes#resource_type_values
    for supported values for resource.type.'
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 17
  severity: WARNING
  validationUnitName: LintValidationUnits/ResourceTypeLiteralCheck

RestrictedAttributesCheck

Exemplo de condição:

{
  "title": "Condition with restricted attribute",
  "description": "",
  "expression": "'accessPolicies/123/accesslevels/TRUSTED' in request.auth.access_levels"
}

Comando de execução:

gcloud alpha iam policies lint-condition --condition-from-file="condition.json"

Resultado da inspeção:

lintResults:
- debugMessage: Condition attribute `request.auth.access_levels` is restricted
    or unsupported. Please check https://cloud.google.com/iam/docs/conditions-overview
    for the full list of supported attributes
  fieldName: condition.expression
  level: CONDITION
  locationOffset: 57
  severity: WARNING
  validationUnitName: LintValidationUnits/RestrictedAttributesCheck