Stratégies concernant les fonctions d'analyse lint

Cet article explique comment exécuter les fonctions d'analyse lint sur vos stratégies Cloud IAM (Cloud Identity and Access Management) ou les valider.

Avant de commencer

Comprendre les fonctions d'analyse lint pour les stratégies Cloud IAM

Dans le contexte des stratégies Cloud IAM, l'analyse lint est une méthode qui consiste à examiner une stratégie existante ou nouvelle et à la vérifier pour détecter des problèmes spécifiques. Ces problèmes incluent les possibilités suivantes :

  • Suggestions
  • Avertissements
  • Informations susceptibles d'améliorer l'objectif de la stratégie, telles qu'une syntaxe et une sémantique améliorées
  • Erreurs de syntaxe ou de sémantique qui entraîneront l'échec des opérations setIamPolicy

Les fonctions d'analyse lint peuvent être utilisées comme outil de débogage pour fournir des explications détaillées sur toute opération setIamPolicy() qui a échoué. Elles peuvent également être utilisées en tant qu'outil auxiliaire pour faciliter la création d'une stratégie IAM afin d'atteindre le résultat prévu.

Exécuter les fonctions d'analyse lint sur une condition

Les expressions de condition peuvent souvent devenir complexes, en particulier dans les cas où plusieurs clauses et opérateurs logiques limitent l'accès de manière appropriée. Si une expression de condition contient une logique non valide ou si la syntaxe ne respecte pas les restrictions d'une expression de condition, l'opération setIamPolicy() échoue. En outre, même lorsqu'une condition peut satisfaire à toutes les exigences strictes de syntaxe et de sémantique pour la mise à jour des stratégies, elle peut quand même contenir des constructions qui entraînent des résultats d'accès inattendus lors de l'application de la stratégie. Voici quelques exemples de cas de ce type :

  • Utilisation de fonctions non recommandées
  • Utilisation d'anciens types de ressources ou d'anciens noms de service
  • Conditions inefficaces, telles qu'une date ou une période non applicable

L'exécution de fonctions d'analyse lint sur une condition entraîne une inspection approfondie et permet de signaler les échecs de mise à jour des stratégies, ainsi que les échecs dus à des constructions contestables.

Avant d'essayer de définir une nouvelle liaison de rôle conditionnelle, il est recommandé d'exécuter d'abord les fonctions d'analyse lint sur l'expression. Cette section vous montre comment exécuter les fonctions d'analyse lint sur une expression de condition à l'aide de Cloud Console, de l'outil de ligne de commande gcloud ou de l'API REST.

Pour exécuter les fonctions d'analyse lint sur une expression de condition, procédez comme suit :

Console

  1. Dans Cloud Console, accédez à la page IAM.

    Accéder à la page "IAM"

  2. Cliquez sur Sélectionner un projet, choisissez un projet et cliquez sur Ouvrir.

  3. Dans la liste des membres, localisez le membre souhaité, puis cliquez sur le bouton .

  4. Dans le panneau Modifier les autorisations, localisez le rôle sur lequel vous souhaitez exécuter les fonctions d'analyse lint. Sous Condition, cliquez sur le nom de la condition.

  5. Dans le panneau Modifier la condition, l'Éditeur de conditions offre la possibilité d'exécuter les fonctions d'analyse lint sur l'expression. Actuellement, le Créateur de conditions a une fonctionnalité d'analyse lint limitée.

  6. Dans l'Éditeur de conditions, ajoutez ou modifiez manuellement une expression de condition.

  7. Pour valider la syntaxe CEL, cliquez sur Exécuter l'outil lint au-dessus de la zone de texte en haut à droite. Si la syntaxe contient des erreurs, une icône apparaît à côté de chaque ligne de l'expression. Si vous placez le pointeur de la souris sur l'icône, le message d'erreur correspondant à cette partie de l'expression s'affiche et fournit des commentaires exploitables pour le débogage.

    Nous vous recommandons de corriger les erreurs avant d'enregistrer la condition. Si les conditions au niveau de la syntaxe sont correctes, mais que l'opération lint trouve des constructions contestables, une icône d'avertissement () s'affiche. Si vous placez le pointeur de la souris sur l'icône, le message d'avertissement correspondant à cette partie de l'expression s'affiche et fournit des commentaires exploitables pour le débogage. Bien qu'il soit fortement recommandé de corriger les avertissements avant d'enregistrer la condition, cette action n'est pas obligatoire.

  8. Apportez les modifications nécessaires à l'expression de condition. Une fois que la commande Exécuter l'outil lint a été déclenchée, les fonctions d'analyse lint restent en arrière-plan pour faciliter la modification de l'expression.

  9. Une fois que les fonctions d'analyse lint ont été appliquées sur l'expression, cliquez sur Enregistrer pour appliquer la condition.

  10. Une fois le panneau Modifier la condition fermé, cliquez à nouveau sur Enregistrer dans le panneau Modifier les autorisations pour mettre à jour votre stratégie Cloud IAM.

gcloud

Exécutez la commande gcloud alpha iam policies lint-condition pour exécuter les fonctions d'analyse lint sur une expression de condition donnée. Pour exécuter cette commande, vous pouvez soit créer un fichier texte contenant la condition, soit spécifier des options pour le titre, la description et l'expression de la condition.

Dans l'exemple ci-dessous, nous allons utiliser un fichier texte contenant la condition suivante :

condition.json

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

Commande :

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

Le résultat de la commande contient les éléments suivants :

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

Chacun des résultats de l'analyse lint contient un message debugMessage qui peut être utilisé pour identifier le problème au niveau de l'expression de condition. Si la condition ne peut pas être compilée, vous pouvez voir de nombreux types d'éléments validationUnitNamedebugMessage avec le texte suivant :

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

Apportez les modifications nécessaires pour compiler l'expression, puis essayez d'exécuter à nouveau l'analyse lint sur la condition.

REST

La méthode iamPolicies.lintPolicy permet d'exécuter des fonctions d'analyse lint sur une expression de condition dans une stratégie IAM, ou de la valider.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

Méthode HTTP et URL :

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

Corps JSON de la requête :

{
  "condition": {
    condition
  }
}

Pour envoyer votre requête, développez l'une des options suivantes :

Le corps de la réponse contient un ou plusieurs objets LintResult, tels que les suivants :

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

Chacun des résultats de l'analyse lint contient un message debug_message qui peut être utilisé pour identifier le problème au niveau de l'expression de condition. Si la condition ne peut pas être compilée, vous pouvez voir de nombreux types d'éléments validation_unit_name avec le texte suivant debugMessage :

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

Apportez les modifications nécessaires pour compiler l'expression, puis essayez d'exécuter à nouveau l'analyse lint sur l'expression de condition.

Unités de validation acceptées

Comme décrit dans la section ci-dessus, une unité de validation est un type d'analyse lint qui évalue l'expression pour rechercher des problèmes de syntaxe. Le tableau ci-dessous récapitule les unités de validation acceptées, chacune avec un niveau d'analyse lint approprié, une gravité des résultats d'analyse lint et une brève description.

Unité de validation Niveau d'analyse lint Gravité Description
ConditionCompileCheck CONDITION ERROR L'expression de condition contient une erreur de compilation due à une syntaxe CEL non valide.
ConditionComplexityCheck CONDITION ERROR L'expression de condition contient plus de 12 opérateurs logiques autorisés.
DateTimeCheck CONDITION WARNING L'expression de condition indique qu'une comparaison d'horodatage est effectivement vraie ou fausse, en raison d'un format d'horodatage incorrect (autre que ISO 8601), de l'horodatage d'expiration défini dans le passé ou de l'horodatage de début défini dans le passé.
DateTimeRangeCheck CONDITION WARNING Valeur hors plage pour la fonction d'horodatage avancée prévue et l'expression de comparaison. Consultez cette section pour connaître la plage de valeurs valide pour les fonctions d'horodatage avancées.
EffectiveTimeRangeCheck CONDITION WARNING Dans une utilisation plus complexe des fonctions d'horodatage et de comparaison, l'expression donne lieu à une période de validité effective vide et est donc effectivement fausse. Sinon, la plage de dates couvre une plage complète et est donc effectivement vraie.
ResourceServiceLiteralCheck CONDITION WARNING La valeur resource.service spécifiée n'est pas acceptée. L'expression utilisant une telle chaîne littérale pour la comparaison d'égalité est effectivement fausse. Consultez cette section pour connaître les valeurs acceptées.
ResourceTypeLiteralCheck CONDITION WARNING La valeur resource.type spécifiée n'est pas acceptée. L'expression utilisant une telle chaîne littérale pour la comparaison d'égalité est effectivement fausse. Consultez cette section pour connaître les valeurs acceptées.
RestrictedAttributesCheck CONDITION WARNING L'expression utilise un attribut actuellement limité ou non disponible. La définition de l'expression de condition peut échouer. Consultez cette section pour consulter la liste des attributs et les étapes de release.

Exemples de fonctions d'analyse lint

Cette section fournit des exemples de stratégies d'analyse lint appliquées à chaque unité de validation. Pour chaque unité de validation, l'exemple de saisie problématique est fourni. Chaque exemple illustre l'utilisation de l'outil de ligne de commande gcloud pour exécuter des fonctions d'analyse lint.

ConditionCompileCheck

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

DateTimeCheck

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

EffectiveTimeRangeCheck

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

ResourceServiceLiteralCheck

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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

Exemple d'expression de condition :

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

Exécuter la commande :

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

Résultat de l'analyse lint :

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