View a markdown version of this page

Validación de plantillas con Guard - AWS CloudFormation

Validación de plantillas con Guard

AWS CloudFormation Guard (cfn-guard) es una herramienta de política como código. Usted escribe reglas en el lenguaje Guard que describen las configuraciones obligatorias o prohibidas; luego, Guard comprueba si los datos JSON o YAML cumplen dichas reglas. Por ejemplo, puede exigir que todos los buckets de Amazon S3 de una plantilla utilicen cifrado o bloquear las reglas de los grupos de seguridad que abren el puerto 22 a Internet.

Guard funciona con cualquier dato de JSON o YAML. Además de las plantillas de CloudFormation, puede consultar los conjuntos de cambios de CloudFormation y los elementos de configuración de AWS Config. Este tema se centra en la comprobación de plantillas.

Para ver las notas de la versión y la referencia completa de comandos, consulte Guard en GitHub. Para obtener una referencia completa sobre el lenguaje, consulte la guía del usuario de Guard.

Para conocer las limitaciones de la validación local y los pasos a seguir antes de la implementación, consulte Descripción del alcance de validación.

Instalación de Guard

En macOS, instale Guard con Homebrew:

brew install cloudformation-guard

En Linux o macOS, en su lugar, puede ejecutar el script de instalación. El script instala la versión más reciente en ~/.guard/bin. Agregue ese directorio a su PATH cuando finalice el script.

curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/aws-cloudformation/cloudformation-guard/main/install-guard.sh | sh

Si tiene una cadena de herramientas de Rust, también puede instalar Guard con Cargo:

cargo install cfn-guard

Para confirmar la instalación, imprima la versión instalada:

cfn-guard --version

Para ver la instalación de Windows, una imagen de Docker y la verificación de la versión, consulte Configuración de Guard.

Comprender el lenguaje de Guard

Ahora que Guard está instalado, puede empezar a escribir reglas. Las reglas de Guard se construyen a partir de las siguientes partes:

  • Consultas: seleccione valores de los datos con una ruta punteada, como Resources.MyBucket.Properties.BucketName. Use * para seleccionar todos los valores de un mapa y [*] para seleccionar todos los elementos de una lista. Agregue un filtro entre corchetes para reducir la selección. Por ejemplo, Resources.*[ Type == 'AWS::S3::Bucket' ] selecciona todos los buckets de Amazon S3.

  • Cláusulas: haga una afirmación que dé como resultado verdadera o falsa. Una cláusula combina una consulta con un operador, como ==, !=, >=, in, exists, empty o is_string. Todas las cláusulas de líneas separadas deben pasar. Para aceptar cualquiera de las dos cláusulas, únalas con or.

  • Variables: almacene el resultado de una consulta con let y haga referencia a él más adelante con un prefijo %. Las variables le permiten seleccionar un conjunto de recursos una vez y reutilizarlo en varias reglas.

  • Reglas con nombre: agrupe las cláusulas de un bloque rule con un nombre. Agregue una condición when para omitir la regla cuando no se aplique, por ejemplo, cuando una plantilla no tiene buckets de Amazon S3. Las reglas pueden hacer referencia a otras reglas, por lo que puede crear políticas complejas a partir de piezas pequeñas.

  • Mensajes personalizados: agregue texto entre << y >> después de una cláusula para explicar un error en el resultado.

Para ver la sintaxis completa, consulte Escritura de reglas de Guard.

Escritura de una regla

Guarde las reglas en un archivo con la extensión .guard. El siguiente ejemplo en rules.guard requiere que cada bucket de Amazon S3 de una plantilla especifique el cifrado del bucket y bloquee el acceso público:

let s3_buckets = Resources.*[ Type == 'AWS::S3::Bucket' ] rule S3_BUCKET_ENCRYPTED when %s3_buckets !empty { %s3_buckets.Properties.BucketEncryption exists << Violation: S3 buckets must specify BucketEncryption. Fix: Add a BucketEncryption property with ServerSideEncryptionConfiguration. >> } rule S3_BUCKET_PUBLIC_ACCESS_BLOCKED when %s3_buckets !empty { %s3_buckets.Properties.PublicAccessBlockConfiguration { BlockPublicAcls == true BlockPublicPolicy == true IgnorePublicAcls == true RestrictPublicBuckets == true } }

La primera línea almacena todos los buckets de Amazon S3 en la variable s3_buckets. Cada regla se ejecuta solo cuando la plantilla contiene al menos un bucket. La primera regla comprueba que la propiedad BucketEncryption existe e incluye un mensaje que Guard imprime cuando la comprobación no se realiza correctamente. La segunda regla comprueba cuatro propiedades dentro de PublicAccessBlockConfiguration. Como las cláusulas están en líneas separadas, las cuatro deben pasar.

Puede guardar varias reglas en un archivo o dividirlas en archivos por tema, por ejemplo, un archivo para las reglas de almacenamiento y otro para las reglas de red. Guard evalúa todos los archivos .guard de un directorio cuando se pasa el directorio a un comando.

Validación de una plantilla

Pase el archivo de reglas a --rules y la plantilla a --data. Agregue --type CFNTemplate para que Guard indique los resultados por identificador lógico del recurso.

cfn-guard validate --rules rules.guard --data template.yaml --type CFNTemplate

Cuando la plantilla pasa, Guard imprime un estado PASS y devuelve el código de salida 0. Cuando se produce un error en una regla, Guard enumera las reglas que han fallado y, por cada recurso que no cumple, la comprobación que ha fallado, la ruta de la propiedad y el motivo. El resultado de una plantilla cuyo bucket le falta BucketEncryption comienza de la siguiente manera:

template.yaml Status = FAIL FAILED rules rules.guard/S3_BUCKET_ENCRYPTED FAIL --- Evaluating data template.yaml against rules rules.guard Number of non-compliant resources 1 Resource = MyBucket { Type = AWS::S3::Bucket Rule = S3_BUCKET_ENCRYPTED { ...

Guard devuelve el código de salida 19 cuando una o más reglas fallan y 5 cuando no puede analizar una regla o un archivo de datos. Puede usar estos códigos de salida para detener una compilación automática.

Las siguientes opciones son útiles a la hora de validar plantillas:

  • Pase --rules o --data más de una vez, o pase un directorio, para comprobar varios archivos de reglas o plantillas en una sola ejecución. Un directorio que pase a --data debe contener solo archivos de datos y un directorio que pase a --rules debe contener solo archivos de reglas.

  • Utilice --show-summary con pass, fail, skip, all o none para controlar qué reglas aparecen en la tabla de resumen. El valor predeterminado es fail.

  • Use --output-format con json, yaml, junit o sarif para producir resultados para otras herramientas. Los formatos junit y sarif funcionan con la mayoría de los sistemas de compilación y herramientas de análisis de código.

  • Use --input-parameters para pasar un archivo JSON o YAML con valores a los que hacen referencia sus reglas, como una lista de identificadores de grupos de seguridad aprobados. Esto evita que los valores específicos del entorno se incluyan en sus reglas.

Para ver todas las opciones, consulte validar en la guía del usuario de Guard.

Pruebe sus reglas

Antes de usar una regla en un flujo de trabajo automatizado, pruébela con el soporte integrado de pruebas unitarias. Un archivo de prueba muestra las entradas de ejemplo y el resultado esperado para cada regla: PASS, FAIL o SKIP. En el siguiente ejemplo de rules_tests.yaml se comprueba la regla S3_BUCKET_ENCRYPTED del ejemplo anterior:

--- - input: Resources: {} expectations: rules: S3_BUCKET_ENCRYPTED: SKIP - input: Resources: MyBucket: Type: AWS::S3::Bucket Properties: {} expectations: rules: S3_BUCKET_ENCRYPTED: FAIL - input: Resources: MyBucket: Type: AWS::S3::Bucket Properties: BucketEncryption: ServerSideEncryptionConfiguration: - ServerSideEncryptionByDefault: SSEAlgorithm: aws:kms expectations: rules: S3_BUCKET_ENCRYPTED: PASS

Ejecute las pruebas con el comando test:

cfn-guard test --rules-file rules.guard --test-data rules_tests.yaml

Guard imprime PASS o FAIL para cada expectativa y devuelve el código de salida 7 cuando no se cumple alguna expectativa. Para más información, consulte Probar reglas de Guard.

Generar reglas a partir de una plantilla

Para empezar rápidamente, puede generar reglas a partir de una plantilla que ya cumpla con sus requisitos. El comando rulegen lee la plantilla y escribe una regla para cada tipo de recurso que requiere los valores de propiedad que se encuentran en la plantilla:

cfn-guard rulegen --template template.yaml --output generated.guard

Revise el archivo generado y conserve solo las comprobaciones que representen su política. Las reglas generadas son un punto de partida y, a menudo, requieren los valores exactos de la plantilla de origen, lo que puede resultar demasiado estricto para otras plantillas.

Incorporación de Guard a su flujo de trabajo

Puede ejecutar Guard en los siguientes lugares:

  • En su editor: el servidor de lenguaje de CloudFormation ejecuta paquetes de reglas de Guard mientras edita una plantilla y muestra los errores en línea. Para obtener información sobre la configuración, consulte Servidor de lenguaje de CloudFormation.

  • Antes de una confirmación de Git: Guard proporciona un enlace pre-commit que puede ejecutar validate en plantillas modificadas o test en reglas modificadas. Agregue lo siguiente a su archivo .pre-commit-config.yaml y reemplace las rutas por las suyas:

    repos: - repo: https://github.com/aws-cloudformation/cloudformation-guard rev: pre-commit-v0.0.2 hooks: - id: cfn-guard args: - --operation=validate - --rules=rules/ files: ^templates/.*
  • En una compilación automática: ejecute cfn-guard validate como un paso de compilación y use el código de salida para que la compilación falle. Utilice --output-format junit o --output-format sarif para publicar los resultados. También están disponibles una GitHub Action y una imagen de contenedor. Extraiga la imagen de public.ecr.aws/aws-cloudformation/cloudformation-guard.

  • Con cloudformation-validate: el comando cfn-validate y el complemento de validación AWS CDK pueden ejecutar un subconjunto compatible de reglas de Guard junto con sus comprobaciones integradas. Para obtener más información, consulte Validación de plantillas con cloudformation-validate.

  • Durante las operaciones de pila: para aplicar reglas cuando la API de CloudFormation o Cloud Control cree, actualice o elimine recursos, utilice Guard Hooks. Para obtener más información, consulte Guard Hooks.

Para ver las reglas listas para usar que cubren los controles comunes de seguridad y cumplimiento, consulte AWS Guard Rules Registry en GitHub.