Análisis de políticas con lint

En este tema, se describe cómo analizar con lint (validar) las políticas de administración de identidades y accesos (IAM).

Antes de comenzar

Información sobre el análisis con lint para las políticas de IAM

En el contexto de las políticas de IAM, el análisis con lint es un método para examinar una política nueva o existente y verificar si tiene problemas específicos. Entre esas cuestiones se incluye el siguiente rango de posibilidades:

  • Sugerencias
  • Advertencias
  • Información que puede ayudar a mejorar la intención de la política, como un uso sintáctico y semántico más adecuado
  • Errores sintácticos o semánticos que no permitirán que se completen correctamente las operaciones setIamPolicy

El análisis con lint de una política puede usarse como herramienta de depuración para proporcionar una explicación detallada de cualquier operación setIamPolicy() que no se complete de forma correcta. También se puede usar como la herramienta de ayuda a fin de facilitar la creación de una política de IAM para lograr el resultado deseado.

Análisis de una condición con lint

Las expresiones de condición a menudo pueden volverse complejas, en especial en situaciones que requieren varias cláusulas y operadores lógicos para restringir el acceso de manera adecuada. Si una expresión de condición contiene lógica no válida o si la sintaxis infringe las restricciones de una expresión de condición, no se completará correctamente la operación setIamPolicy(). Además, a pesar de que una condición pase todos los requisitos estrictos de sintaxis y semántica para la actualización de políticas, podría contener construcciones que generen resultados de acceso inesperados durante la aplicación de las políticas. Estos son algunos ejemplos de estos casos:

  • Uso de funciones no recomendadas
  • Uso de tipos de recursos heredados o nombres de servicios heredados
  • Condiciones ineficaces, como una fecha o un intervalo de tiempo inaplicables

Cuando se lleve a cabo un análisis con lint de una condición, se realizará una inspección detallada y, además, se informarán las fallas que puedan ocurrir en la actualización de la política y otras construcciones cuestionables.

Antes de que intentes establecer una nueva vinculación de función condicional, te recomendamos que analices la expresión con lint. En esta sección se explica cómo analizar una expresión de condición con lint mediante Cloud Console, la herramienta de línea de comandos de gcloud o la API de REST.

Para analizar una expresión de condición con lint, haz lo siguiente:

Console

  1. En Cloud Console, ve a la página IAM.

    Ir a la página IAM

  2. Haz clic en Seleccionar un proyecto, elige un proyecto y haz clic en Abrir.

  3. En la lista de miembros, busca el miembro deseado y haz clic en el botón .

  4. En el panel Editar permisos, busca la función que deseas analizar con lint. Luego, en Condición, haz clic en el nombre de la condición.

  5. En el panel Editar condición, el Editor de condición proporciona la capacidad de analizar la expresión con lint. Actualmente la funcionalidad de análisis con lint del Creador de condiciones es limitada.

  6. En el Editor de condición, agrega o edita una expresión de condición de forma manual.

  7. Para validar la sintaxis de CEL, haz clic en Ejecutar lint arriba del cuadro de texto en la parte superior derecha. Si la sintaxis tiene errores, aparecerá un ícono  junto a cada línea de la expresión. Si colocas el cursor sobre el ícono, aparecerá el mensaje de error para esa parte de la expresión y se indicarán acciones posibles para la depuración.

    Te recomendamos corregir los errores antes de guardar la condición. Si las condiciones son correctas en cuanto a la sintaxis, pero en la operación lint encuentran construcciones cuestionables, aparecerá un ícono de advertencia (). Si colocas el cursor sobre el ícono, aparecerá el mensaje de advertencia para esa parte de la expresión y se indicarán acciones posibles para la depuración. Si bien es recomendable corregir las advertencias antes de guardar la condición, no es un requisito ineludible.

  8. Realiza los cambios necesarios en la expresión de condición. Después de que se active Ejecutar lint, el análisis con lint continuará en segundo plano para facilitar la edición de la expresión.

  9. Después de que la expresión se haya analizado con lint de forma correcta, haz clic en Guardar para aplicar la condición.

  10. Una vez que el panel Editar condición esté cerrado, vuelve a hacer clic en Guardar desde el panel Editar permisos para actualizar la política de IAM.

Comando de gcloud

Ejecuta el comando gcloud alpha iam policies lint-condition para analizar con lint una expresión de condición determinada. Para ejecutar este comando puedes crear un archivo de texto que contenga la condición o especificar marcas para el título, la descripción y la expresión de la condición.

En el siguiente ejemplo usaremos un archivo de texto que contenga la condición:

condition.json

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

Comando:

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

El resultado del comando contiene lo siguiente:

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 uno de los resultados del análisis con lint contiene un debugMessage que se puede usar para ayudar a localizar el problema de la expresión de condición. Si la condición no se compiló, es posible que veas muchos tipos de validationUnitName diferentes con el siguiente texto de debugMessage:

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

Realiza los cambios necesarios para que la expresión se compile de forma correcta y, luego, intenta analizar la condición con lint otra vez.

API de REST

El método iamPolicies.lintPolicy analiza con lint o valida una expresión de condición en una política de IAM.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • condition: Un objeto Expr que representa la condición para analizar con lint. Por ejemplo:

    "title": "1_less_than_2",
    "description": "",
    "expression": "1 <"
    
    Si quieres obtener más información sobre el formato de un objeto Expr, consulta la referencia del esquema de Expr.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

{
  "condition": {
    condition
  }
}

Para enviar tu solicitud, expande una de estas opciones:

El cuerpo de la respuesta contiene uno o más objetos LintResult, como los siguientes:

{
  "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 uno de los resultados de lint contiene un debug_message que se puede usar para ayudar a localizar el problema de la expresión de condición. Si la condición no se compiló, es posible que veas muchos tipos de validation_unit_name diferentes con el siguiente texto de debugMessage:

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

Realiza los cambios necesarios para que la expresión se compile de forma correcta y, luego, intenta analizar la expresión de condición con lint otra vez.

Unidades de validación compatibles

Como se describió en la sección anterior, la unidad de validación es un tipo de lint individual que evalúa la expresión para detectar problemas sintácticos. En la siguiente tabla se resumen las unidades de validación compatibles, cada una con el nivel de análisis con lint previsto, la gravedad de los resultados del análisis con lint y una breve descripción.

Unidad de validación Nivel de análisis con lint Gravedad Descripción
ConditionCompileCheck CONDITION ERROR La expresión de condición tiene un error de compilación como resultado de una sintaxis CEL no válida.
ConditionComplexityCheck CONDITION ERROR La expresión de condición tiene más de 12 operadores lógicos, que es la cantidad máxima.
DateTimeCheck CONDITION WARNING La expresión de condición indica que una comparación de marca de tiempo es efectivamente verdadera o falsa, debido a un formato de marca de tiempo no válido (que no sea ISO 8601), o bien la marca de tiempo de vencimiento o la marca de tiempo de inicio corresponde a una hora o fecha en el pasado.
DateTimeRangeCheck CONDITION WARNING Valor fuera del rango para la función de marca de tiempo avanzada deseada y la expresión de comparación. Consulta aquí el rango de valores válido para las funciones de marca de tiempo avanzadas.
EffectiveTimeRangeCheck CONDITION WARNING En un uso más complejo de funciones de marca de tiempo y comparación, la expresión devuelve un intervalo de tiempo efectivo vacío y, por lo tanto, resulta efectivamente falso. Como alternativa el intervalo de tiempo abarca un rango completo y, por lo tanto, resulta efectivamente verdadero.
ResourceServiceLiteralCheck CONDITION WARNING No se admite el valor resource.service especificado. La expresión que usa ese valor literal de string para la comparación de igualdad es efectivamente falsa. Consulta aquí los valores admitidos.
ResourceTypeLiteralCheck CONDITION WARNING No se admite el valor resource.type especificado. La expresión que usa ese valor literal de string para la comparación de igualdad es efectivamente falsa. Consulta aquí los valores admitidos.
RestrictedAttributesCheck CONDITION WARNING La expresión usa un atributo que está restringido o que no es compatible en este momento. Es posible que no se pueda realizar la configuración de la expresión de condición. Consulta aquí la lista de atributos y las etapas de lanzamiento.

Ejemplos de análisis con lint

En esta sección se proporcionan ejemplos del uso del análisis de políticas con lint por unidad de validación. Para cada unidad de validación, se proporciona un ejemplo de entrada que causa problemas. Cada ejemplo ilustra el análisis con lint empleando la herramienta de línea de comandos de gcloud

ConditionCompileCheck

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de 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

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de lint:

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

DateTimeCheck

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de 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

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de 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

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de lint:

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

ResourceServiceLiteralCheck

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de 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

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de 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

Ejemplo de expresión de condición:

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

Ejecuta el siguiente comando:

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

Resultado de lint:

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