Lint-Richtlinien

alpha feature

In diesem Thema wird beschrieben, wie Sie Ihre Cloud IAM-Richtlinien (Cloud Identity and Access Management) mit Linting validieren.

Hinweise

Informationen zum Linting für Cloud IAM-Richtlinien

Im Rahmen von Cloud IAM-Richtlinien wird Linting als Methode eingesetzt, um neue oder bestehende Richtlinien auf bestimmte Probleme hin zu prüfen. Hierbei kann es sich beispielsweise um folgende Probleme handeln:

  • Vorschläge
  • Warnungen
  • Informationen, die zur Verbesserung der Absicht der Richtlinie beitragen können, z. B. bessere Syntax und Semantik
  • Syntax- oder Semantikfehler, die dazu führen, dass setIamPolicy Vorgänge fehlschlagen

Das Linting einer Richtlinie kann als Debugging-Tool verwendet werden, um eine detaillierte Erklärung für fehlgeschlagene setIamPolicy()-Vorgänge bereitzustellen. Es kann auch als Tool zum Erstellen einer Cloud IAM-Richtlinie verwendet werden, um das gewünschte Ergebnis zu erzielen.

Linting einer Bedingung

Bedingungsausdrücke können häufig komplex werden, insbesondere in Szenarien, in denen mehrere Klauseln und logische Operatoren erforderlich sind, um den Zugriff angemessen einzuschränken. Wenn ein Bedingungsausdruck eine ungültige Logik enthält oder die Syntax gegen die Einschränkungen eines Bedingungsausdrucks verstößt, schlägt der Vorgang setIamPolicy() fehl. Außerdem kann eine Bedingung zwar alle strengen Syntax- und Semantikanforderungen für die Richtlinienaktualisierung erfüllen, sie kann jedoch weiterhin Konstrukte enthalten, die bei der Richtlinienerzwingung möglicherweise zu unerwarteten Zugriffsergebnissen führen. Beispiele für solche Fälle sind die Verwendung nicht empfohlener Funktionen, die Verwendung von Legacy-Ressourcentypnamen, ineffiziente Bedingungen (Datum/Uhrzeit in der Vergangenheit) usw. Das Linting einer Bedingung führt eine gründliche Prüfung durch und meldet sowohl Fehler, die bei der Richtlinienaktualisierung auftreten können, als auch andere fragwürdige Konstrukte.

Bevor Sie eine neue bedingte Rollenbindung festlegen, sollten Sie den Ausdruck zuerst per Linting verknüpfen. In diesem Abschnitt erfahren Sie, wie Sie Linting für einen Bedingungsausdruck mithilfe der Cloud Console, des gcloud-Befehlszeilentools oder der REST API durchführen.

So führen Sie Linting für einen Bedingungsausdruck durch:

Console

  1. Öffnen Sie in der Cloud Console die Seite "IAM".

    Zur Seite "IAM"

  2. Klicken Sie auf Projekt auswählen, wählen Sie ein Projekt aus und klicken Sie auf Öffnen.

  3. Suchen Sie in der Mitgliederliste nach dem gewünschten Mitglied und klicken Sie auf die Schaltfläche .

  4. Wählen Sie im Feld Berechtigungen bearbeiten die gewünschte Rolle aus, für die Sie Linting durchführen möchten. Klicken Sie dann unter Bedingung auf den Namen der Bedingung.

  5. Im Bereich Bedingung bearbeiten bietet der Bedingungseditor die Möglichkeit, den Ausdruck zu löschen. Der Condition Builder verfügt derzeit über eine eingeschränkte Linting-Funktionalität.

  6. Fügen Sie im Bedingungsbearbeiter einen Bedingungsausdruck manuell hinzu oder bearbeiten Sie ihn.

  7. Überprüfen Sie die CEL-Syntax, indem Sie auf Linter ausführen oberhalb des Textfelds oben rechts klicken. Wenn die Syntax Fehler enthält, wird neben jeder Zeile des Ausdrucks das Symbol angezeigt. Wenn Sie den Mauszeiger über das Symbol bewegen, wird die Fehlermeldung für diesen Teil des Ausdrucks angezeigt und Sie erhalten umsetzbares Feedback für den Debugging-Vorgang.

    Wir empfehlen Ihnen, die Fehler vor dem Speichern der Bedingung zu beheben. Wenn die Bedingungen syntaktisch korrekt sind, aber beim Linting fragwürdige Konstrukte ermittelt werden, wird ein Warnsymbol () angezeigt. Wenn Sie den Mauszeiger über das Symbol bewegen, wird die Warnmeldung für diesen Teil des Ausdrucks angezeigt und Sie erhalten umsetzbares Feedback für den Debugging-Vorgang. Obwohl dies dringend empfohlen wird, ist es nicht zwingend erforderlich, die Warnungen vor dem Speichern der Bedingung zu korrigieren.

  8. Nehmen Sie die erforderlichen Änderungen am Bedingungsausdruck vor. Nachdem Linter ausführen ausgelöst wurde, wird es weiterhin im Hintergrund ausgeführt, um die Bearbeitung des Ausdrucks zu erleichtern.

  9. Nachdem der Ausdruck erfolgreich gelöscht wurde, klicken Sie auf Speichern, um die Bedingung anzuwenden.

  10. Sobald das Feld Bedingung bearbeiten geschlossen wurde, klicken Sie noch einmal auf Speichern im Feld Berechtigungen bearbeiten, um Ihre Cloud IAM-Richtlinie zu aktualisieren.

gcloud-Befehl

Führen Sie den Befehl gcloud alpha iam policies lint-condition aus, um einen bestimmten Bedingungsausdruck zu filtern. Um diesen Befehl auszuführen, können Sie entweder eine Textdatei erstellen, die die Bedingung enthält, oder Flags für den Titel, die Beschreibung und den Ausdruck der Bedingung angeben.

Im folgenden Beispiel verwenden wir eine Textdatei, die die Bedingung enthält:

condition.json

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

Befehl:

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

Die Ausgabe des Befehls enthält Folgendes:

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

Jedes der Lint-Ergebnisse enthält eine debugMessage, die zur Lokalisierung des Problems mit dem Bedingungsausdruck verwendet werden kann. Wenn die Bedingung nicht kompiliert werden konnte, sehen Sie möglicherweise viele verschiedene validationUnitName-Typen mit dem folgenden debugMessage-Text:

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

Nehmen Sie alle erforderlichen Änderungen vor, damit der Ausdruck erfolgreich kompiliert wird, und versuchen Sie dann noch einmal, die Bedingung zu filtern.

REST API

Rufen Sie lintPolicy() auf, um das Linting für den Bedingungsausdruck durchzuführen:

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

Der Anfragetext enthält den Bedingungsausdruck:

{
        "condition": {
          "title": "1_less_than_2",
          "description": "",
          "expression": "1 &lt;"
        }
    }
    

Der Antworttext enthält ein oder mehrere LintResult-Objekte, z. B.:

{
      "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 \'&lt;EOF&gt;\' expecting {\'[\', \'{\', \'(\', \'.\', \'-\', \'!\', \'true\', \'false\', \'null\', NUM_FLOAT, NUM_INT, NUM_UINT, STRING, BYTES, IDENTIFIER}\n  | 1&lt;\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"
      }
    }
    

Jedes der Lint-Ergebnisse enthält eine debug_message, die zur Lokalisierung des Problems mit dem Bedingungsausdruck verwendet werden kann. Wenn die Bedingung nicht kompiliert werden konnte, sehen Sie möglicherweise viele verschiedene validation_unit_name-Typen mit dem folgenden debugMessage-Text:

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

Nehmen Sie alle erforderlichen Änderungen vor, damit der Ausdruck erfolgreich kompiliert wird, und versuchen Sie dann noch einmal, den Bedingungsausdruck zu filtern.

Unterstützte Validierungseinheiten

Wie im Abschnitt oben beschrieben, ist eine Validierungseinheit ein individueller Lint-Typ, der den Ausdruck auf syntaktische Probleme hin auswertet. In der folgenden Tabelle sind die unterstützten Validierungseinheiten zusammengefasst, jeweils mit der beabsichtigten Linting-Ebene, dem Schweregrad der Linting-Ergebnisse und einer kurzen Beschreibung.

Validierungseinheit Lint-Ebene Severity Beschreibung
ConditionCompileCheck CONDITION ERROR Der Bedingungsausdruck enthält einen Kompilierungsfehler aufgrund ungültiger CEL-Syntax.
ConditionComplexityCheck CONDITION ERROR Der Bedingungsausdruck enthält mehr als die maximal zulässige Anzahl von zwölf logischen Operatoren.
DateTimeCheck CONDITION WARNING Der Bedingungsausdruck gibt an, dass ein Zeitstempelvergleich aufgrund eines ungültigen Zeitstempelformats (nicht ISO 8601) effektiv wahr oder falsch ist oder der Ablaufzeitstempel bzw. Startzeitstempel in der Vergangenheit liegt.
DateTimeRangeCheck CONDITION WARNING Der Wert liegt außerhalb des Bereichs für die vorgesehene erweiterte Zeitstempelfunktion und den Vergleichsausdruck. Den gültigen Wertebereich für erweiterte Zeitstempelfunktionen finden Sie hier.
EffectiveTimeRangeCheck CONDITION WARNING Bei einer komplexeren Verwendung von Zeitstempelfunktionen und Vergleichen führt der Ausdruck zu einem leeren effektiven Zeitbereich und ist daher effektiv falsch. Alternativ deckt der Zeitraum einen vollständigen Bereich ab und ist daher effektiv wahr.
ResourceServiceLiteralCheck CONDITION WARNING Der angegebene Wert resource.service wird nicht unterstützt. Der Ausdruck, der ein solches Stringliteral für den Gleichheitsvergleich verwendet, ist effektiv falsch. Unterstützte Werte finden Sie hier.
ResourceTypeLiteralCheck CONDITION WARNING Der angegebene Wert resource.type wird nicht unterstützt. Der Ausdruck, der ein solches Stringliteral für den Gleichheitsvergleich verwendet, ist effektiv falsch. Unterstützte Werte finden Sie hier.
RestrictedAttributesCheck CONDITION WARNING Der Ausdruck verwendet ein Attribut, das sich derzeit in einer privaten Betaversion befindet. Das Festlegen des Bedingungsausdrucks ist aufgrund von Nutzungsbeschränkungen aus der Zugriffssteuerung auf die weiße Liste möglicherweise nicht erfolgreich. Eine Liste der Attribute und Releasephasen finden Sie hier.

Linting-Beispiele

Dieser Abschnitt enthält Beispiele für die Verwendung von Linting-Richtlinien für die einzelnen Validierungseinheiten. Für jede Validierungseinheit wird die problematische Beispieleingabe bereitgestellt. In jedem Beispiel wird das Linting mithilfe des gcloud-Befehlszeilentools veranschaulicht

ConditionCompileCheck

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

DateTimeCheck

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

ResourceServiceLiteralCheck

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispiel-Bedingungsausdruck:

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

Befehl ausführen:

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

Lint-Ergebnis:

lintResults:
    - debugMessage: Condition attribute `request.auth.access_levels` is in private beta
        release and may be subject to whitelist control. Please check https://cloud.google.com/iam/docs/conditions-overview
        for the full list of restricted attributes
      fieldName: condition.expression
      level: CONDITION
      locationOffset: 57
      severity: WARNING
      validationUnitName: LintValidationUnits/RestrictedAttributesCheck