Criteri di analisi tramite lint

Questo argomento descrive come lintare o convalidare i criteri di autorizzazione di Identity and Access Management (IAM).

Prima di iniziare

Ruoli obbligatori

Per eseguire il lint di un criterio di autorizzazione di una risorsa, devi disporre delle autorizzazioni per ottenere la risorsa e per ottenere e impostare il criterio di autorizzazione per la risorsa. Queste autorizzazioni hanno la seguente forma, dove SERVICE è il nome del servizio proprietario della risorsa e RESOURCE_TYPE è il nome del tipo di risorsa a cui vuoi gestire l'accesso:

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

Ad esempio, per eseguire il lint di una policy di autorizzazione di un progetto, devi disporre delle seguenti autorizzazioni:

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

Per ottenere le autorizzazioni richieste, chiedi all'amministratore di concederti un ruolo predefinito o personalizzato che includa le autorizzazioni. Ad esempio, l'amministratore potrebbe concederti il ruolo diAmministratore sicurezzaa (roles/iam.securityAdmin), che include le autorizzazioni per ottenere quasi tutte le risorseGoogle Cloud e gestire i relativi criteri di autorizzazione.

Informazioni sul linting per le policy di autorizzazione

Nel contesto dei criteri di autorizzazione, il linting è un metodo per esaminare un criterio di autorizzazione nuovo o esistente e verificarne la presenza di problemi specifici. Questi problemi includono la seguente gamma di possibilità:

  • Suggerimenti
  • Avvisi
  • Informazioni che possono contribuire a migliorare l'intento della policy di autorizzazione, ad esempio sintassi e semantica migliori
  • Errori di sintassi o semantici che causano il mancato funzionamento delle operazioni setIamPolicy

Se provi ad aggiornare una policy di autorizzazione e ricevi un errore, l'analisi lint della policy di autorizzazione può aiutarti a trovare la causa dell'errore. Puoi anche utilizzare il linter per assicurarti che un binding di ruolo condizionale abbia l'effetto previsto.

Analisi tramite lint di una condizione

Le espressioni di condizione possono essere complesse, soprattutto negli scenari che richiedono più clausole e operatori logici per gestire correttamente l'accesso. Se un'espressione di condizione contiene una logica non valida o se la sintassi viola le limitazioni di un'espressione di condizione, non puoi aggiungere la condizione a un criterio di autorizzazione.

Inoltre, anche se un'espressione di condizione utilizza la sintassi corretta, potrebbe contenere errori semantici, che possono impedire il corretto funzionamento delle policy di autorizzazione e delle associazioni di ruoli. Gli errori semantici comuni includono:

  • Utilizzo di funzioni non consigliate
  • Utilizzo di tipi di risorse legacy o nomi di servizi legacy
  • Condizioni inefficaci, ad esempio un intervallo di date o ore non applicabile

Quando esegui l'analisi lint di una condizione, il linter esamina l'espressione della condizione e segnala eventuali errori di sintassi. Segnala anche possibili errori semantici che potrebbero causare risultati imprevisti.

Prima di tentare di impostare un nuovo binding del ruolo condizionale, ti consigliamo di eseguire il lint dell'espressione. Questa sezione mostra come eseguire il lint di un'espressione di condizione utilizzando la console Google Cloud , Google Cloud CLI o l'API REST.

Per eseguire il lint di un'espressione della condizione:

Console

  1. Nella console Google Cloud vai alla pagina IAM.

    Vai a IAM

  2. Fai clic su Seleziona un progetto, scegli un progetto e fai clic su Apri.

  3. Nell'elenco delle entità, individua quella che ti interessa e fai clic sul pulsante Modifica.

  4. Nel riquadro Modifica autorizzazioni, individua il ruolo che vuoi analizzare. Poi, in Condizione IAM (facoltativo), fai clic sul nome della condizione.

  5. Nell'editor delle condizioni, aggiungi o modifica manualmente un'espressione di condizione.

  6. Per convalidare la sintassi CEL, fai clic su Esegui Linter.

    Se la sintassi contiene errori, viene visualizzata un'icona Errore accanto alla riga errata. Per visualizzare i dettagli di ogni errore, tieni il puntatore sopra l'icona.

    Se la condizione utilizza la sintassi corretta, ma il linter rileva un possibile problema, accanto alla riga con il problema viene visualizzata un'icona Avviso. Per visualizzare i dettagli di ogni avviso, tieni il puntatore sopra l'icona.

  7. Apporta le modifiche necessarie all'espressione della condizione. Dopo aver fatto clic su Esegui Linter, Linter viene eseguito automaticamente in background mentre modifichi l'espressione.

    Devi correggere tutti gli errori prima di salvare l'espressione della condizione. Ti consigliamo vivamente di correggere anche tutti gli avvisi.

  8. Se non sono presenti errori o avvisi, fai clic su Salva per applicare la condizione.

  9. Una volta chiuso il riquadro Modifica condizione, fai di nuovo clic su Salva nel riquadro Modifica autorizzazioni per aggiornare la policy di autorizzazione.

gcloud

Esegui il comando gcloud alpha iam policies lint-condition per eseguire il lint di una determinata espressione di condizione. Per eseguire questo comando, puoi creare un file di testo contenente la condizione o specificare i flag per il titolo, la descrizione e l'espressione della condizione.

L'esempio seguente utilizza un file di testo contenente la seguente condizione:

condition.json

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

Esegui il comando:

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

L'output del comando contiene quanto segue:

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

Ciascuno dei risultati di lint contiene un debugMessage che può essere utilizzato per individuare il problema con l'espressione della condizione. Se la condizione non è stata compilata, potresti visualizzare molti tipi diversi di validationUnitName con il seguente testo debugMessage:

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

Apporta modifiche in modo che l'espressione venga compilata, quindi esegui di nuovo il controllo della condizione.

REST

Il metodo iamPolicies.lintPolicy esegue il linting o la convalida di un'espressione di condizione in un criterio di autorizzazione.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • condition: un oggetto Expr che rappresenta la condizione da analizzare. Ad esempio: 

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

    Per informazioni sul formato di un oggetto Expr, consulta i riferimenti allo schema Expr.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "condition": {
    condition
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

Il corpo della risposta contiene uno o più oggetti LintResult, ad esempio: 

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

Ciascuno dei risultati di lint contiene un debug_message che può essere utilizzato per individuare il problema con l'espressione della condizione. Se la condizione non è stata compilata, potresti visualizzare molti tipi diversi di validation_unit_name con il seguente testo debugMessage:

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

Apporta modifiche in modo che l'espressione venga compilata, quindi esegui di nuovo il controllo della condizione.

Unità di convalida supportate

Come descritto in precedenza, un'unità di convalida è un singolo tipo di lint che valuta l'espressione per problemi di sintassi. La tabella seguente riepiloga le unità di convalida supportate, ciascuna con il livello di linting previsto, la gravità del risultato del linting e una breve descrizione.

Unità di convalida Livello di lanugine Gravità Descrizione
ConditionCompileCheck CONDITION ERROR L'espressione della condizione contiene un errore di compilazione a causa di una sintassi CEL non valida.
ConditionComplexityCheck CONDITION ERROR L'espressione della condizione contiene più di 12 operatori logici, il numero massimo consentito.
DateTimeCheck CONDITION WARNING

L'espressione di condizione specifica un confronto dei timestamp che restituisce sempre true o false a causa di uno di questi problemi:

DateTimeRangeCheck CONDITION WARNING Valore fuori intervallo per la funzione avanzata di timestamp prevista e l'espressione di confronto. Consulta i valori validi per le funzioni avanzate di timestamp.
DrgGetAttributeDefaultValueCheck CONDITION ERROR L'espressione della condizione chiama api.getAttribute('iam.googleapis.com/modifiedGrantsByRole', V), dove V è un valore diverso da un elenco vuoto, []. Per questo attributo API, V deve essere sempre un elenco vuoto.
EffectiveTimeRangeCheck CONDITION WARNING In un utilizzo più complesso delle funzioni di timestamp e del confronto, l'espressione restituisce un intervallo di tempo effettivo vuoto ed è quindi effettivamente falsa. In alternativa, l'intervallo di tempo copre un intervallo completo, ed è quindi effettivamente vero.
HasOnlyListConstCheck CONDITION ERROR L'espressione della condizione chiama hasOnly(List<T>), dove il tipo T non è un tipo costante, ad esempio una stringa o un numero intero. La funzione hasOnly() accetta solo un elenco di costanti.
HasOnlyListLengthCheck CONDITION ERROR L'espressione della condizione chiama hasOnly(List<T>) e List<T> contiene più del massimo di 10 elementi.
ResourceServiceLiteralCheck CONDITION WARNING Il valore resource.service specificato non è supportato. L'espressione che utilizza questo tipo di stringa letterale per il confronto di uguaglianza è effettivamente falsa. Utilizza un valore supportato.
ResourceTypeLiteralCheck CONDITION WARNING Il valore resource.type specificato non è supportato. L'espressione che utilizza questo tipo di stringa letterale per il confronto di uguaglianza è effettivamente falsa. Utilizza un valore supportato.
RestrictedAttributesCheck CONDITION WARNING L'espressione utilizza un attributo limitato o non supportato. L'impostazione dell'espressione della condizione potrebbe non riuscire. Consulta l'elenco degli attributi.

Esempi di analisi tramite lint

Questa sezione mostra esempi di condizioni che causano problemi per ogni unità di convalida. Ogni esempio mostra il controllo del codice utilizzando Google Cloud CLI.

Nessun problema di convalida

Condizione di esempio:

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

Esegui il comando:

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

Risultato lint:

{}

ConditionCompileCheck

Condizione di esempio:

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

Esegui il comando:

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

Risultato 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

Condizione di esempio:

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

Esegui il comando:

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

Risultato lint:

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

DateTimeCheck

Condizione di esempio:

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

Esegui il comando:

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

Risultato 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

Condizione di esempio:

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

Esegui il comando:

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

Risultato 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

DrgGetAttributeDefaultValueCheck

Condizione di esempio:

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

Esegui il comando:

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

Risultato lint:

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

Condizione di esempio:

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

Esegui il comando:

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

Risultato lint:

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

HasOnlyListConstCheck

Condizione di esempio:

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

Esegui il comando:

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

Risultato lint:

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

Condizione di esempio:

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

Esegui il comando:

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

Risultato lint:

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

Condizione di esempio:

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

Esegui il comando:

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

Risultato 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

Condizione di esempio:

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

Esegui il comando:

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

Risultato 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

Condizione di esempio:

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

Esegui il comando:

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

Risultato 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