As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # AWS CloudFormation Guard Regras de redação Dentro AWS CloudFormation Guard, *regras* são policy-as-code regras. Você escreve regras na linguagem específica de domínio (DSL) do Guard com as quais você pode validar seus dados formatados em JSON ou YAML. As regras são compostas por *cláusulas*. Você pode salvar regras escritas usando o Guard DSL em arquivos de texto simples que usam qualquer extensão de arquivo. Você pode criar vários arquivos de regras e categorizá-los como um *conjunto de regras*. Os conjuntos de regras permitem que você valide seus dados formatados em JSON ou YAML em relação a vários arquivos de regras ao mesmo tempo. **Topics** + [Cláusulas](#clauses) + [Usando consultas em cláusulas](#clauses-queries) + [Usando operadores em cláusulas](#clauses-operators) + [Usando mensagens personalizadas em cláusulas](#clauses-custom-messages) + [Combinando cláusulas](#combining-clauses) + [Usando blocos com regras do Guard](#blocks) + [Usando funções integradas](#built-in-functions) + [Definindo consultas e filtragem do Guard](query-and-filtering.md) + [Atribuição e referência de variáveis nas regras do Guard](variables.md) + [Composição de blocos de regras nomeadas em AWS CloudFormation Guard](named-rule-block-composition.md) + [Escrevendo cláusulas para realizar avaliações contextuais](context-aware-evaluations.md) ## Cláusulas As cláusulas são expressões booleanas que são avaliadas como verdadeiras (`PASS`) ou falsas (`FAIL`). As cláusulas usam operadores binários para comparar dois valores ou operadores unários que operam em um único valor. **Exemplos de cláusulas unárias** A cláusula unária a seguir avalia se a coleção `TcpBlockedPorts` está vazia. ``` InputParameters.TcpBlockedPorts not empty ``` A cláusula unária a seguir avalia se a `ExecutionRoleArn` propriedade é uma string. ``` Properties.ExecutionRoleArn is_string ``` **Exemplos de cláusulas binárias** A cláusula binária a seguir avalia se a `BucketName` propriedade contém a string`encrypted`, independentemente da maiúscula e minúscula. ``` Properties.BucketName != /(?i)encrypted/ ``` A cláusula binária a seguir avalia se a `ReadCapacityUnits` propriedade é menor ou igual a 5.000. ``` Properties.ProvisionedThroughput.ReadCapacityUnits <= 5000 ``` ### Sintaxe para escrever cláusulas de regras do Guard ``` [query|value literal] [custom message] ``` ### Propriedades das cláusulas da regra de guarda `query` Uma expressão separada por ponto (`.`) escrita para atravessar dados hierárquicos. As expressões de consulta podem incluir expressões de filtro para direcionar um subconjunto de valores. As consultas podem ser atribuídas a variáveis para que você possa escrevê-las uma vez e referenciá-las em outro lugar em um conjunto de regras, o que permitirá acessar os resultados da consulta. Para obter mais informações sobre como escrever consultas e filtrar, consulte. [Definição de consultas e filtragem](query-and-filtering.md) *Obrigatório*: sim `operator` Um operador unário ou binário que ajuda a verificar o estado da consulta. O lado esquerdo (LHS) de um operador binário deve ser uma consulta e o lado direito (RHS) deve ser uma consulta ou um valor literal. *Operadores binários suportados*: `==` (Igual) \| `!=` (Diferente) \| `>` (Maior que) \| `>=` (Maior que ou igual a) \| `<` (Menor que) \| `<=` (Menor que ou igual a) \| `IN` (Em uma lista no formato [x, y, z] *Operadores unários suportados*: `exists` \| `empty` \| \| `is_string` \| `is_list` \| `is_struct` `not(!)` *Obrigatório*: sim `query|value literal` Uma consulta ou um valor literal compatível, como `string` ou`integer(64)`. *Literais de valor suportados*: + Todos os tipos primitivos:`string`,`integer(64)`,,`float(64)`,`bool`, `char` `regex` + Todos os tipos de intervalos especializados para expressão `integer(64)``float(64)`, ou `char` intervalos expressos como: + `r[, ]`, que se traduz em qualquer valor `k` que satisfaça a seguinte expressão: `lower_limit <= k <= upper_limit` + `r[, `), que se traduz em qualquer valor `k` que satisfaça a seguinte expressão: `lower_limit <= k < upper_limit` + `r(, ]`, que se traduz em qualquer valor `k` que satisfaça a seguinte expressão: `lower_limit < k <= upper_limit` + `r(, ),`que se traduz em qualquer valor `k` que satisfaça a seguinte expressão: `lower_limit < k < upper_limit` + Matrizes associativas (mapas) para dados de estrutura de valores-chave aninhados. Por exemplo: `{ "my-map": { "nested-maps": [ { "key": 10, "value": 20 } ] } }` + Matrizes de tipos primitivos ou tipos de matrizes associativas *Obrigatório*: Condicional; obrigatório quando um operador binário é usado. `custom message` Uma string que fornece informações sobre a cláusula. A mensagem é exibida nas saídas detalhadas dos `test` comandos `validate` and e pode ser útil para entender ou depurar a avaliação de regras em dados hierárquicos. *Obrigatório*: não ## Usando consultas em cláusulas Para obter informações sobre como escrever consultas, consulte [Definição de consultas e filtragem](query-and-filtering.md) e. [Atribuição e referência de variáveis nas regras do Guard](variables.md) ## Usando operadores em cláusulas A seguir estão exemplos CloudFormation de modelos `Template-1` `Template-2` e. Para demonstrar o uso de operadores compatíveis, os exemplos de consultas e cláusulas nesta seção se referem a esses modelos de exemplo. **Modelo-1** ``` Resources: S3Bucket: Type: AWS::S3::Bucket Properties: BucketName: MyServiceS3Bucket BucketEncryption: ServerSideEncryptionConfiguration: - ServerSideEncryptionByDefault: SSEAlgorithm: 'aws:kms' KMSMasterKeyID: 'arn:aws:kms:us-east-1:123456789:key/056ea50b-1013-3907-8617-c93e474e400' Tags: - Key: stage Value: prod - Key: service Value: myService ``` **Modelo-2** ``` Resources: NewVolume: Type: AWS::EC2::Volume Properties: Size: 100 VolumeType: io1 Iops: 100 AvailabilityZone: Fn::Select: - 0 - Fn::GetAZs: us-east-1 Tags: - Key: environment Value: test DeletionPolicy: Snapshot ``` ### Exemplos de cláusulas que usam operadores unários + `empty`— Verifica se uma coleção está vazia. Você também pode usá-lo para verificar se uma consulta tem valores em dados hierárquicos porque as consultas resultam em uma coleção. Você não pode usá-lo para verificar se as consultas de valor de string têm uma string (`""`) vazia definida. Para obter mais informações, consulte [Definição de consultas e filtragem](query-and-filtering.md). A cláusula a seguir verifica se o modelo tem um ou mais recursos definidos. É avaliado `PASS` porque um recurso com o ID lógico `S3Bucket` está definido em`Template-1`. ``` Resources !empty ``` A cláusula a seguir verifica se uma ou mais tags estão definidas para o `S3Bucket` recurso. É avaliado `PASS` porque `S3Bucket` tem duas tags definidas para a `Tags` propriedade em`Template-1`. ``` Resources.S3Bucket.Properties.Tags !empty ``` + `exists`— Verifica se cada ocorrência da consulta tem um valor e pode ser usada no lugar de`!= null`. A cláusula a seguir verifica se a `BucketEncryption` propriedade está definida para o. `S3Bucket` É avaliado como `PASS` porque `BucketEncryption` está definido para `S3Bucket` em`Template-1`. ``` Resources.S3Bucket.Properties.BucketEncryption exists ``` **nota** As `not exists` verificações `empty` e avaliam a ausência `true` de chaves de propriedade ao percorrer os dados de entrada. Por exemplo, se a `Properties` seção não estiver definida no modelo para o`S3Bucket`, a cláusula será `Resources.S3Bucket.Properties.Tag empty` avaliada como. `true` As `empty` verificações `exists` e não exibem o caminho do ponteiro JSON dentro do documento nas mensagens de erro. Ambas as cláusulas geralmente têm erros de recuperação que não mantêm essas informações de travessia. + `is_string`— Verifica se cada ocorrência da consulta é do `string` tipo. A cláusula a seguir verifica se um valor de string foi especificado para a `BucketName` propriedade do `S3Bucket` recurso. É avaliado como `PASS` porque o valor da string `"MyServiceS3Bucket"` é especificado para `BucketName` in`Template-1`. ``` Resources.S3Bucket.Properties.BucketName is_string ``` + `is_list`— Verifica se cada ocorrência da consulta é do `list` tipo. A cláusula a seguir verifica se uma lista foi especificada para a `Tags` propriedade do `S3Bucket` recurso. É avaliado como `PASS` porque dois pares de valores-chave são especificados em. `Tags` `Template-1` ``` Resources.S3Bucket.Properties.Tags is_list ``` + `is_struct`— Verifica se cada ocorrência da consulta é um dado estruturado. A cláusula a seguir verifica se os dados estruturados estão especificados para a `BucketEncryption` propriedade do `S3Bucket` recurso. É avaliado como `PASS` porque `BucketEncryption` é especificado usando o tipo de `ServerSideEncryptionConfiguration` propriedade {{(object)}} em`Template-1`. ``` Resources.S3Bucket.Properties.BucketEncryption is_struct ``` **nota** Para verificar o estado inverso, você pode usar o operador (` not !`) com os `is_struct` operadores `is_string``is_list`, e. ### Exemplos de cláusulas que usam operadores binários A cláusula a seguir verifica se o valor especificado para a `BucketName` propriedade do `S3Bucket` recurso em `Template-1` contém a string`encrypt`, independentemente da maiúscula e minúscula. Isso acontece `PASS` porque o nome do bucket especificado `"MyServiceS3Bucket"` não contém a string`encrypt`. ``` Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ ``` A cláusula a seguir verifica se o valor especificado para a `Size` propriedade do `NewVolume` recurso em `Template-2` está dentro de um intervalo específico: 50 <= `Size` <= 200. É avaliado como `PASS` porque `100` está especificado para`Size`. ``` Resources.NewVolume.Properties.Size IN r[50,200] ``` A cláusula a seguir verifica se o valor especificado para a `VolumeType` propriedade do `NewVolume` recurso em `Template-2` é `io1``io2`, ou`gp3`. É avaliado como `PASS` porque `io1` está especificado para`NewVolume`. ``` Resources.NewVolume.Properties.NewVolume.VolumeType IN [ 'io1','io2','gp3' ] ``` **nota** Os exemplos de consultas nesta seção demonstram o uso de operadores usando os recursos com lógica IDs `S3Bucket` e. `NewVolume` Os nomes dos recursos geralmente são definidos pelo usuário e podem ser nomeados arbitrariamente em um modelo de infraestrutura como código (IaC). Para escrever uma regra que seja genérica e se aplique a todos os `AWS::S3::Bucket` recursos definidos no modelo, a forma mais comum de consulta usada é`Resources.*[ Type == ‘AWS::S3::Bucket’ ]`. Para obter mais informações, consulte [Definição de consultas e filtragem](query-and-filtering.md) para obter detalhes sobre o uso e explore o diretório de [exemplos](https://github.com/aws-cloudformation/cloudformation-guard/tree/main/guard-examples) no `cloudformation-guard` GitHub repositório. ## Usando mensagens personalizadas em cláusulas No exemplo a seguir, cláusulas para `Template-2` incluir uma mensagem personalizada. ``` Resources.NewVolume.Properties.Size IN r(50,200) << EC2Volume size must be between 50 and 200, not including 50 and 200 >> Resources.NewVolume.Properties.VolumeType IN [ 'io1','io2','gp3' ] <> ``` ## Combinando cláusulas No Guard, cada cláusula escrita em uma nova linha é combinada implicitamente com a próxima cláusula usando conjunção (lógica booleana). `and` Veja o exemplo a seguir. ``` # clause_A ^ clause_B ^ clause_C clause_A clause_B clause_C ``` Você também pode usar a disjunção para combinar uma cláusula com a próxima cláusula especificando `or|OR` no final da primeira cláusula. ``` [query|value literal] [custom message] [or|OR] ``` Em uma cláusula de Guarda, as disjunções são avaliadas primeiro, seguidas pelas conjunções. As regras de proteção podem ser definidas como uma conjunção de disjunção de cláusulas (e `and|AND` de `or|OR` s) que são avaliadas como () ou `true` (`PASS`). `false` `FAIL` Isso é semelhante à forma [normal conjuntiva](https://en.wikipedia.org/wiki/Conjunctive_normal_form). Os exemplos a seguir demonstram a ordem das avaliações das cláusulas. ``` # (clause_E v clause_F) ^ clause_G clause_E OR clause_F clause_G # (clause_H v clause_I) ^ (clause_J v clause_K) clause_H OR clause_I clause_J OR clause_K # (clause_L v clause_M v clause_N) ^ clause_O clause_L OR clause_M OR clause_N clause_O ``` Todas as cláusulas baseadas no exemplo `Template-1` podem ser combinadas usando a conjunção. Veja o exemplo a seguir. ``` Resources.S3Bucket.Properties.BucketName is_string Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ Resources.S3Bucket.Properties.BucketEncryption exists Resources.S3Bucket.Properties.BucketEncryption is_struct Resources.S3Bucket.Properties.Tags is_list Resources.S3Bucket.Properties.Tags !empty ``` ## Usando blocos com regras do Guard Blocos são composições que removem a verbosidade e a repetição de um conjunto de cláusulas, condições ou regras relacionadas. Existem três tipos de blocos: + Blocos de consulta + `when`blocos + Blocos de regras nomeadas ### Blocos de consulta A seguir estão as cláusulas baseadas no exemplo`Template-1`. A conjunção foi usada para combinar as cláusulas. ``` Resources.S3Bucket.Properties.BucketName is_string Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ Resources.S3Bucket.Properties.BucketEncryption exists Resources.S3Bucket.Properties.BucketEncryption is_struct Resources.S3Bucket.Properties.Tags is_list Resources.S3Bucket.Properties.Tags !empty ``` Partes da expressão de consulta em cada cláusula são repetidas. Você pode melhorar a composição e remover a verbosidade e a repetição de um conjunto de cláusulas relacionadas com o mesmo caminho de consulta inicial usando um bloco de consulta. O mesmo conjunto de cláusulas pode ser escrito conforme mostrado no exemplo a seguir. ``` Resources.S3Bucket.Properties { BucketName is_string BucketName != /(?i)encrypt/ BucketEncryption exists BucketEncryption is_struct Tags is_list Tags !empty } ``` Em um bloco de consulta, a consulta anterior ao bloco define o contexto das cláusulas dentro do bloco. Para obter mais informações sobre o uso de blocos, consulte[Composição de blocos de regras nomeadas](named-rule-block-composition.md). ### `when`blocos Você pode avaliar blocos condicionalmente usando `when` blocos, que assumem o seguinte formato. ``` when { Guard_rule_1 Guard_rule_2 ... } ``` A `when` palavra-chave designa o início do `when` bloco. `condition`é uma regra da Guarda. O bloco só é avaliado se a avaliação da condição resultar em `true` (`PASS`). A seguir está um exemplo de `when` bloco baseado em`Template-1`. ``` when Resources.S3Bucket.Properties.BucketName is_string { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` A cláusula dentro do `when` bloco só é avaliada se o valor especificado `BucketName` for uma string. Se o valor especificado para `BucketName` for referenciado na `Parameters` seção do modelo, conforme mostrado no exemplo a seguir, a cláusula dentro do `when` bloco não será avaliada. ``` Parameters: S3BucketName: Type: String Resources: S3Bucket: Type: AWS::S3::Bucket Properties: BucketName: Ref: S3BucketName ... ``` ### Blocos de regras nomeadas *Você pode atribuir um nome a um conjunto de regras (conjunto de regras) e, em seguida, referenciar esses blocos de validação modulares, chamados de blocos *de regras nomeadas*, em outras regras.* Os blocos de regras nomeadas assumem o seguinte formato. ``` rule [when ] { Guard_rule_1 Guard_rule_2 ... } ``` A `rule` palavra-chave designa o início do bloco de regras nomeadas. `rule name`é uma string legível por humanos que identifica de forma exclusiva um bloco de regras nomeadas. É um rótulo para o conjunto de regras do Guard que ele encapsula. Nesse uso, o termo *regra de proteção* inclui cláusulas, blocos de consulta, blocos e `when` blocos de regras nomeadas. O nome da regra pode ser usado para se referir ao resultado da avaliação do conjunto de regras que ela encapsula, o que torna os blocos de regras nomeadas reutilizáveis. O nome da regra também fornece contexto sobre falhas de regras nas saídas do `test` comando `validate` e. O nome da regra é exibido junto com o status de avaliação do bloco (`PASS``FAIL`, ou`SKIP`) na saída de avaliação do arquivo de regras. Veja o exemplo a seguir. ``` # Sample output of an evaluation where check1, check2, and check3 are rule names. template.json Status = **FAIL** **SKIP rules** check1 **SKIP** **PASS rules** check2 **PASS** **FAILED rules** check3 **FAIL** ``` Você também pode avaliar blocos de regras nomeadas condicionalmente especificando a `when` palavra-chave seguida por uma condição após o nome da regra. A seguir está o `when` bloco de exemplo que foi discutido anteriormente neste tópico. ``` rule checkBucketNameStringValue when Resources.S3Bucket.Properties.BucketName is_string { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Usando blocos de regras nomeadas, o precedente também pode ser escrito da seguinte forma. ``` rule checkBucketNameIsString { Resources.S3Bucket.Properties.BucketName is_string } rule checkBucketNameStringValue when checkBucketNameIsString { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Você pode reutilizar e agrupar blocos de regras nomeadas com outras regras do Guard. A seguir estão alguns exemplos. ``` rule rule_name_A { Guard_rule_1 OR Guard_rule_2 ... } rule rule_name_B { Guard_rule_3 Guard_rule_4 ... } rule rule_name_C { rule_name_A OR rule_name_B } rule rule_name_D { rule_name_A rule_name_B } rule rule_name_E when rule_name_D { Guard_rule_5 Guard_rule_6 ... } ``` ## Usando funções integradas AWS CloudFormation Guard fornece funções integradas que você pode usar em suas regras para realizar operações como manipulação de strings, análise de JSON e conversão de tipo de dados. As funções são suportadas somente por meio da atribuição a uma variável. ### Funções-chave `json_parse(json_string)` Analisa cadeias de caracteres JSON embutidas a partir de um modelo. Após a análise, você pode avaliar as propriedades do objeto resultante. `count(collection)` Retorna o número de itens para os quais uma consulta é resolvida. `regex_replace(base_string, regex_to_extract, regex_replacement)` Substitui partes de uma string usando expressões regulares. Para obter uma lista completa das funções disponíveis, incluindo manipulação de strings, operações de coleta e funções de conversão de tipo de dados, consulte a [documentação de funções](https://github.com/aws-cloudformation/cloudformation-guard/blob/main/docs/FUNCTIONS.md) no GitHub repositório Guard.