Lint-Richtlinien

In diesem Abschnitt wird beschrieben, wie Sie Ihre Zulassungsrichtlinien (Identity and Access Management) mit Lint validieren.

Vorbereitung

Erforderliche Rollen

Wenn Sie die Zulassungsrichtlinie einer Ressource mit Lint analysieren möchten, benötigen Sie Berechtigungen zum Abrufen der Ressource und zum Abrufen und Festlegen der Zulassungsrichtlinie für die Ressource. Diese Berechtigungen haben das folgende Format, wobei SERVICE der Name des Dienstes ist, zu dem die Ressource gehört, und RESOURCE_TYPE der Name des Ressourcentyps, für den Sie den Zugriff verwalten möchten:

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

Wenn Sie beispielsweise die Zulassungsrichtlinie eines Projekts mit Lint analysieren möchten, benötigen Sie die folgenden Berechtigungen:

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

Bitten Sie Ihren Administrator, Ihnen eine vordefinierte oder benutzerdefinierte Rolle zuzuweisen, die die Berechtigungen enthält. Beispielsweise kann Ihr Administrator Ihnen die Rolle des Sicherheitsadministrators (roles/iam.securityAdmin) zuweisen, die Berechtigungen zum Abrufen von fast allen Google Cloud-Ressourcen und zum Verwalten ihrer Zulassungsrichtlinien enthält.

Informationen zum Linting für Zulassungsrichtlinien

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

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

Wenn Sie versuchen, eine Zulassungsrichtlinie zu aktualisieren und eine Fehlermeldung erhalten, können Sie die Ursache durch Validierung der Zulassungsrichtlinie mit Lint korrigieren. Sie können mit dem Linter auch dafür sorgen, dass eine bedingte Rollenbindung den gewünschten Effekt hat.

Linting einer Bedingung

Bedingungsausdrücke können komplex sein, insbesondere in Szenarien, in denen mehrere Klauseln und Logikoperatoren erforderlich sind, um den Zugriff richtig zu verwalten. Wenn ein Bedingungsausdruck ungültige Logik enthält oder die Syntax gegen die Einschränkungen eines Bedingungsausdrucks verstößt, können Sie die Bedingung nicht einer Zulassungsrichtlinie hinzufügen.

Auch wenn ein Bedingungsausdruck die richtige Syntax verwendet, kann er semantische Fehler enthalten, durch die Ihre Zulassungsrichtlinie und Rollenbindungen nicht wie erwartet funktionieren. Zu den häufigsten semantischen Fehlern gehören:

  • Verwendung von nicht empfohlenen Funktionen
  • Verwendung von Legacy-Ressourcentypen oder Legacy-Dienstnamen
  • Unwirksame Bedingungen, z. B. ein ungültiger Datums- oder Zeitraum

Wenn Sie eine Bedingung per Lint testen, prüft der Linter den Bedingungsausdruck und meldet alle Syntaxfehler. Außerdem werden mögliche semantische Fehler gemeldet, die zu unerwarteten Ergebnissen führen können.

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 Google Cloud Console, der Google Cloud CLI oder der REST API durchführen.

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

Console

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

    IAM aufrufen

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

  3. Suchen Sie in der Liste der Hauptkonten das gewünschte Hauptkonto und klicken Sie auf die Schaltfläche Bearbeiten.

  4. Suchen Sie im Bereich Berechtigungen bearbeiten die gewünschte Rolle, für die Sie Linting durchführen möchten. Klicken Sie dann unter IAM-Bedingung (optional) auf den Namen der Bedingung.

  5. Fügen Sie im Bedingungseditor einen Bedingungsausdruck manuell hinzu oder bearbeiten Sie ihn.

  6. Klicken Sie zum Validieren der CEL-Syntax auf Linter ausführen.

    Wenn die Syntax Fehler enthält, wird neben der falschen Zeile das Symbol Fehler angezeigt. Details zu jedem Fehler können Sie aufrufen, indem Sie den Mauszeiger auf das Symbol bewegen.

    Wenn die Bedingung die richtige Syntax verwendet, der Linter jedoch ein mögliches Problem identifiziert, wird neben der Zeile mit dem Problem das Symbol Warnung angezeigt. Details zu den einzelnen Warnungen sehen Sie, wenn Sie den Mauszeiger auf das Symbol bewegen.

  7. Nehmen Sie die erforderlichen Änderungen am Bedingungsausdruck vor. Nachdem Sie auf Linter ausführen geklickt haben, wird der Linter automatisch im Hintergrund ausgeführt, während Sie den Ausdruck bearbeiten.

    Sie müssen alle Fehler korrigieren, bevor Sie den Bedingungsausdruck speichern können. Wir empfehlen Ihnen außerdem, alle Warnungen ebenfalls zu korrigieren.

  8. Wenn keine Fehler oder Warnungen vorhanden sind, klicken Sie auf Speichern, um die Bedingung anzuwenden.

  9. Sobald der Bereich Bedingung bearbeiten geschlossen wurde, klicken Sie im Bereich Berechtigungen bearbeiten noch einmal auf Speichern, um die Zulassungsrichtlinie zu aktualisieren.

gcloud

Wenden Sie Linting mit dem Befehl gcloud alpha iam policies lint-condition auf einen bestimmten Bedingungsausdruck an. Zur Ausführung dieses Befehls können Sie entweder eine Textdatei mit der Bedingung erstellen oder Flags für den Titel, die Beschreibung und den Ausdruck der Bedingung angeben.

Im folgenden Beispiel wird eine Textdatei verwendet, die folgende Bedingung enthält:

condition.json

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

Befehl ausführen:

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 zum Auffinden 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 Änderungen vor, damit der Ausdruck kompiliert wird, und wiederholen Sie dann das Linting der Bedingung noch einmal.

REST

Mit der Methode iamPolicies.lintPolicy wird für einen Bedingungsausdruck in einer Zulassungsrichtlinie das Linting bzw. die Validierung ausgeführt.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • condition: Ein Expr-Objekt, das die Bedingung darstellt, für die das Linting durchgeführt werden soll. Beispiel: 

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

    Weitere Informationen zum Format eines Expr-Objekts finden Sie in der Expr-Schemareferenz.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "condition": {
    condition
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

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 \'<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"
  }
}

Jedes der Lint-Ergebnisse enthält eine debug_message, die zum Auffinden 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 Änderungen vor, damit der Ausdruck kompiliert wird, und wiederholen Sie dann das Linting der Bedingung noch einmal.

Unterstützte Validierungseinheiten

Wie bereits erwähnt, ist eine Validierungseinheit ein einzelner Lint-Typ, der den Ausdruck auf Syntaxprobleme prüft. Die folgende Tabelle fasst die unterstützten Validierungseinheiten zusammen, jeweils mit der beabsichtigten Linting-Stufe, dem Schweregrad der Linting-Ergebnisse und einer kurzen Beschreibung.

Validierungseinheit Lint-Stufe Schweregrad Beschreibung
ConditionCompileCheck CONDITION ERROR Der Bedingungsausdruck enthält einen Kompilierungsfehler aufgrund einer ungültigen CEL-Syntax.
ConditionComplexityCheck CONDITION ERROR Der Bedingungsausdruck enthält mehr als die maximal 12 logischen Operatoren.
DateTimeCheck CONDITION WARNING

Der Bedingungsausdruck gibt einen Zeitstempelvergleich an, der je nach den folgenden Problemen immer als "true" oder "false" ausgewertet wird:

DateTimeRangeCheck CONDITION WARNING Wert außerhalb des Bereichs für die vorgesehene erweiterte Zeitstempelfunktion und den Vergleichsausdruck. Informationen zu erweiterten Zeitstempelfunktionen finden Sie unter Gültige Werte.
DrgGetAttributeDefaultValueCheck CONDITION ERROR Der Bedingungsausdruck ruft api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', V) auf, wobei V ein beliebiger Wert außer einer leeren Liste ist: []. Für dieses API-Attribut muss V immer eine leere Liste sein.
EffectiveTimeRangeCheck CONDITION WARNING Bei einer komplexeren Verwendung von Zeitstempelfunktionen und Vergleichen führt der Ausdruck zu einem leeren effektiven Zeitraum und ist daher effektiv falsch. Alternativ deckt der Zeitraum einen vollständigen Bereich ab und ist daher effektiv wahr.
HasOnlyListConstCheck CONDITION ERROR Der Bedingungsausdruck ruft hasOnly(List<T>) auf, wobei der Typ T kein konstanter Typ ist, wie beispielsweise ein String oder eine Ganzzahl. Die Funktion hasOnly() akzeptiert nur eine Liste von Konstanten.
HasOnlyListLengthCheck CONDITION ERROR Der Bedingungsausdruck ruft hasOnly(List<T>) auf und List<T> enthält mehr als die maximal zulässige Anzahl von zehn Elementen.
ResourceServiceLiteralCheck CONDITION WARNING Der angegebene Wert für resource.service wird nicht unterstützt. Der Ausdruck, der ein solches String-Literal für den Gleichheitsvergleich verwendet, ist effektiv falsch. Verwenden Sie einen unterstützten Wert.
ResourceTypeLiteralCheck CONDITION WARNING Der angegebene Wert für resource.type wird nicht unterstützt. Der Ausdruck, der ein solches String-Literal für den Gleichheitsvergleich verwendet, ist effektiv falsch. Verwenden Sie einen unterstützten Wert.
RestrictedAttributesCheck CONDITION WARNING Der Ausdruck verwendet ein Attribut, das derzeit eingeschränkt ist oder nicht unterstützt wird. Das Festlegen des Bedingungsausdrucks ist möglicherweise nicht erfolgreich. Weitere Informationen finden Sie in der Liste der Attribute.

Beispiele für Linting

In diesem Abschnitt finden Sie Beispiele für Bedingungen, die dazu führen, dass jede Validierungseinheit Probleme meldet. In jedem Beispiel wird Linting mithilfe von Google Cloud CLI gezeigt.

Bei der Prüfung wurden keine Fehler gefunden.

Beispielbedingung:

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

Befehl ausführen:

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

Lint-Ergebnis:

{}

ConditionCompileCheck

Beispielbedingung:

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

Beispielbedingung:

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

Beispielbedingung:

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

Beispielbedingung:

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

DrgGetAttributeDefaultValueCheck

Beispielbedingung:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispielbedingung:

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

HasOnlyListConstCheck

Beispielbedingung:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispielbedingung:

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

Befehl ausführen:

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

Lint-Ergebnis:

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

Beispielbedingung:

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

Beispielbedingung:

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

Beispielbedingung:

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