Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # AWS CloudFormation Guard Regole di scrittura *In, le regole sono regole. AWS CloudFormation Guard* policy-as-code Scrivi regole nel linguaggio DSL (Domain-Specific Language) Guard in base alle quali puoi convalidare i tuoi dati in formato JSON o YAML. *Le regole sono costituite da clausole.* È possibile salvare le regole scritte utilizzando Guard DSL in file di testo semplice che utilizzano qualsiasi estensione di file. *È possibile creare più file di regole e classificarli come set di regole.* I set di regole consentono di convalidare i dati in formato JSON o YAML rispetto a più file di regole contemporaneamente. **Topics** + [Clausole](#clauses) + [Utilizzo di interrogazioni nelle clausole](#clauses-queries) + [Utilizzo degli operatori nelle clausole](#clauses-operators) + [Utilizzo di messaggi personalizzati nelle clausole](#clauses-custom-messages) + [Combinazione di clausole](#combining-clauses) + [Utilizzo di blocchi con regole Guard](#blocks) + [Utilizzo delle funzioni integrate](#built-in-functions) + [Definizione delle interrogazioni e del filtraggio di Guard](query-and-filtering.md) + [Assegnazione e riferimento a variabili nelle regole di Guard](variables.md) + [Composizione di blocchi con regole denominate in AWS CloudFormation Guard](named-rule-block-composition.md) + [Scrittura di clausole per eseguire valutazioni basate sul contesto](context-aware-evaluations.md) ## Clausole Le clausole sono espressioni booleane che restituiscono true () o false ()`PASS`. `FAIL` Le clausole utilizzano operatori binari per confrontare due valori o operatori unari che operano su un singolo valore. **Esempi di clausole unarie** La seguente clausola unaria valuta se la raccolta è vuota. `TcpBlockedPorts` ``` InputParameters.TcpBlockedPorts not empty ``` La seguente clausola unaria valuta se la proprietà è una stringa. `ExecutionRoleArn` ``` Properties.ExecutionRoleArn is_string ``` **Esempi di clausole binarie** La clausola binaria seguente valuta se la `BucketName` proprietà contiene la stringa`encrypted`, indipendentemente dal maiuscolo. ``` Properties.BucketName != /(?i)encrypted/ ``` La clausola binaria seguente valuta se la `ReadCapacityUnits` proprietà è inferiore o uguale a 5.000. ``` Properties.ProvisionedThroughput.ReadCapacityUnits <= 5000 ``` ### Sintassi per scrivere le clausole delle regole di Guard ``` [query|value literal] [custom message] ``` ### Proprietà delle clausole delle regole Guard `query` Un'espressione separata da punti (`.`) scritta per attraversare dati gerarchici. Le espressioni di query possono includere espressioni di filtro destinate a un sottoinsieme di valori. Le query possono essere assegnate alle variabili in modo da poterle scrivere una sola volta e fare riferimento ad esse altrove in un set di regole, il che consentirà di accedere ai risultati delle query. Per ulteriori informazioni sulla scrittura di interrogazioni e sui filtri, vedere. [Definizione di interrogazioni e filtri](query-and-filtering.md) *Obbligatorio:* sì `operator` Un operatore unario o binario che consente di controllare lo stato della query. Il lato sinistro (LHS) di un operatore binario deve essere una query, mentre il lato destro (RHS) deve essere una query o un valore letterale. *Operatori binari supportati*: `==` (Uguale) \| `!=` (Non uguale) \| `>` (Maggiore di) \| `>=` (Maggiore o uguale a) \| `<` (Minore di) \| `<=` (Minore o uguale a) \| `IN` (In un elenco in forma [x, y, z] *Operatori unari supportati*: `exists` \| `empty` \| \| `is_string` \| `is_list` \| `is_struct` `not(!)` *Obbligatorio:* sì `query|value literal` Una query o un valore letterale supportato come `string` o. `integer(64)` *Valori letterali supportati*: + Tutti i tipi primitivi:`string`,,`integer(64)`,,`float(64)`, `bool` `char` `regex` + Tutti i tipi di intervalli specializzati per esprimere `integer(64)` o `char` intervalli espressi come: `float(64)` + `r[, ]`, che si traduce in qualsiasi valore `k` che soddisfi la seguente espressione: `lower_limit <= k <= upper_limit` + `r[, `), che si traduce in qualsiasi valore `k` che soddisfi la seguente espressione: `lower_limit <= k < upper_limit` + `r(, ]`, che si traduce in qualsiasi valore `k` che soddisfi la seguente espressione: `lower_limit < k <= upper_limit` + `r(, ),`che si traduce in qualsiasi valore `k` che soddisfi la seguente espressione: `lower_limit < k < upper_limit` + Matrici associative (mappe) per dati di struttura chiave-valore annidati. Esempio: `{ "my-map": { "nested-maps": [ { "key": 10, "value": 20 } ] } }` + Matrici di tipi primitivi o tipi di array associativi *Obbligatorio*: condizionale; richiesto quando si utilizza un operatore binario. `custom message` Una stringa che fornisce informazioni sulla clausola. Il messaggio viene visualizzato negli output dettagliati dei `test` comandi `validate` and e può essere utile per comprendere o eseguire il debug della valutazione delle regole sui dati gerarchici. *Obbligatorio:* no ## Utilizzo di interrogazioni nelle clausole Per informazioni sulla scrittura di interrogazioni, vedere e. [Definizione di interrogazioni e filtri](query-and-filtering.md) [Assegnazione e riferimento a variabili nelle regole di Guard](variables.md) ## Utilizzo degli operatori nelle clausole Di seguito sono riportati CloudFormation modelli di esempio e`Template-1`. `Template-2` Per dimostrare l'uso degli operatori supportati, le query e le clausole di esempio in questa sezione fanno riferimento a questi modelli di esempio. **Modello-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 ``` **Modello-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 ``` ### Esempi di clausole che utilizzano operatori unari + `empty`— Controlla se una raccolta è vuota. È inoltre possibile utilizzarlo per verificare se una query contiene valori in un dato gerarchico, poiché le query generano una raccolta. Non è possibile utilizzarlo per verificare se le query con valori di stringa hanno una stringa vuota () definita. `""` Per ulteriori informazioni, consulta [Definizione di interrogazioni e filtri](query-and-filtering.md). La clausola seguente verifica se il modello ha una o più risorse definite. Viene restituito `PASS` perché una risorsa con l'ID logico `S3Bucket` è definita in. `Template-1` ``` Resources !empty ``` La clausola seguente verifica se uno o più tag sono definiti per la `S3Bucket` risorsa. Il risultato è `PASS` perché `S3Bucket` ha due tag definiti per la `Tags` proprietà in. `Template-1` ``` Resources.S3Bucket.Properties.Tags !empty ``` + `exists`— Verifica se ogni occorrenza dell'interrogazione ha un valore e può essere utilizzata al posto di`!= null`. La clausola seguente verifica se la `BucketEncryption` proprietà è definita per. `S3Bucket` Restituisce `PASS` perché `BucketEncryption` è definito per `S3Bucket` in. `Template-1` ``` Resources.S3Bucket.Properties.BucketEncryption exists ``` **Nota** I `not exists` controlli `empty` e restituiscono le chiavi `true` di proprietà mancanti durante l'attraversamento dei dati di input. Ad esempio, se la `Properties` sezione non è definita nel modello di`S3Bucket`, la clausola restituisce lo stesso risultato`Resources.S3Bucket.Properties.Tag empty`. `true` I `empty` controlli `exists` and non visualizzano il percorso del puntatore JSON all'interno del documento nei messaggi di errore. Entrambe queste clausole presentano spesso errori di recupero che non mantengono queste informazioni trasversali. + `is_string`— Verifica se ogni occorrenza dell'interrogazione è di tipo. `string` La clausola seguente verifica se è specificato un valore di stringa per la `BucketName` proprietà della `S3Bucket` risorsa. Viene restituito `PASS` perché il valore della stringa `"MyServiceS3Bucket"` è specificato per `BucketName` in. `Template-1` ``` Resources.S3Bucket.Properties.BucketName is_string ``` + `is_list`— Verifica se ogni occorrenza dell'interrogazione è di `list` tipo. La clausola seguente verifica se è specificato un elenco per la `Tags` proprietà della `S3Bucket` risorsa. Viene restituito `PASS` perché per in sono state specificate due coppie chiave-valore. `Tags` `Template-1` ``` Resources.S3Bucket.Properties.Tags is_list ``` + `is_struct`— Verifica se ogni occorrenza della query è costituita da dati strutturati. La clausola seguente verifica se i dati strutturati sono specificati per la `BucketEncryption` proprietà della `S3Bucket` risorsa. Viene restituito `PASS` perché `BucketEncryption` è specificato utilizzando il tipo {{(object)}} di `ServerSideEncryptionConfiguration` proprietà in. `Template-1` ``` Resources.S3Bucket.Properties.BucketEncryption is_struct ``` **Nota** Per verificare lo stato inverso, è possibile utilizzare l'operatore (` not !`) con gli operatori `is_string``is_list`, e`is_struct`. ### Esempi di clausole che utilizzano operatori binari La clausola seguente verifica se il valore specificato per la `BucketName` proprietà della `S3Bucket` risorsa in `Template-1` contiene la stringa`encrypt`, indipendentemente dal maiuscolo e minuscolo. Il risultato è che il `PASS` nome del bucket specificato `"MyServiceS3Bucket"` non contiene la stringa. `encrypt` ``` Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ ``` La clausola seguente verifica se il valore specificato per la `Size` proprietà della `NewVolume` risorsa in rientra in `Template-2` un intervallo specifico: 50 <= `Size` <= 200. Restituisce `PASS` perché `100` è specificato per. `Size` ``` Resources.NewVolume.Properties.Size IN r[50,200] ``` La clausola seguente verifica se il valore specificato per la `VolumeType` proprietà della `NewVolume` risorsa in `Template-2` è `io1``io2`, o. `gp3` Restituisce `PASS` perché `io1` è specificato per. `NewVolume` ``` Resources.NewVolume.Properties.NewVolume.VolumeType IN [ 'io1','io2','gp3' ] ``` **Nota** Le query di esempio in questa sezione dimostrano l'uso di operatori che utilizzano le risorse con logico IDs `S3Bucket` and. `NewVolume` I nomi delle risorse sono spesso definiti dall'utente e possono essere denominati arbitrariamente in un modello Infrastructure as Code (IaC). Per scrivere una regola generica e applicabile a tutte le `AWS::S3::Bucket` risorse definite nel modello, la forma di interrogazione più comune utilizzata è. `Resources.*[ Type == ‘AWS::S3::Bucket’ ]` Per ulteriori informazioni, consulta [Definizione di interrogazioni e filtri](query-and-filtering.md) i dettagli sull'utilizzo ed esplora la directory [degli esempi](https://github.com/aws-cloudformation/cloudformation-guard/tree/main/guard-examples) nel `cloudformation-guard` GitHub repository. ## Utilizzo di messaggi personalizzati nelle clausole Nell'esempio seguente, le clausole per `Template-2` includere un messaggio personalizzato. ``` 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' ] <> ``` ## Combinazione di clausole In Guard, ogni clausola scritta su una nuova riga viene combinata implicitamente con la clausola successiva utilizzando la congiunzione (logica booleana). `and` Guarda l'esempio seguente. ``` # clause_A ^ clause_B ^ clause_C clause_A clause_B clause_C ``` È inoltre possibile utilizzare la disgiunzione per combinare una clausola con la clausola successiva specificando alla fine della prima clausola. `or|OR` ``` [query|value literal] [custom message] [or|OR] ``` In una clausola Guard, le disgiunzioni vengono valutate per prime, seguite dalle congiunzioni. Le regole Guard possono essere definite come una combinazione di clausole (e di `or|OR` s) che danno come risultato () o (). `and|AND` `true` `PASS` `false` `FAIL` [È simile alla forma normale congiuntiva.](https://en.wikipedia.org/wiki/Conjunctive_normal_form) Gli esempi seguenti mostrano l'ordine di valutazione delle clausole. ``` # (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 ``` Tutte le clausole basate sull'esempio `Template-1` possono essere combinate utilizzando la congiunzione. Guarda l'esempio seguente. ``` 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 ``` ## Utilizzo di blocchi con regole Guard I blocchi sono composizioni che rimuovono la verbosità e la ripetizione da un insieme di clausole, condizioni o regole correlate. Esistono tre tipi di blocchi: + Blocchi di query + `when`blocchi + blocchi con regole denominate ### Blocchi di query Di seguito sono riportate le clausole basate sull'esempio. `Template-1` La congiunzione è stata utilizzata per combinare le clausole. ``` 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 ``` Parti dell'espressione di interrogazione in ogni clausola vengono ripetute. È possibile migliorare la componibilità e rimuovere la verbosità e la ripetizione da un set di clausole correlate con lo stesso percorso di interrogazione iniziale utilizzando un blocco di query. È possibile scrivere lo stesso set di clausole come illustrato nell'esempio seguente. ``` Resources.S3Bucket.Properties { BucketName is_string BucketName != /(?i)encrypt/ BucketEncryption exists BucketEncryption is_struct Tags is_list Tags !empty } ``` In un blocco di query, la query che precede il blocco imposta il contesto per le clausole all'interno del blocco. Per ulteriori informazioni sull'uso dei blocchi, vedere. [Composizione di blocchi con regole denominate](named-rule-block-composition.md) ### `when`blocchi È possibile valutare i blocchi in modo condizionale utilizzando `when` i blocchi, che assumono la forma seguente. ``` when { Guard_rule_1 Guard_rule_2 ... } ``` La `when` parola chiave indica l'inizio del `when` blocco. `condition`è una regola della Guardia. Il blocco viene valutato solo se la valutazione della condizione risulta in `true` (`PASS`). Di seguito è riportato un esempio di `when` blocco basato su`Template-1`. ``` when Resources.S3Bucket.Properties.BucketName is_string { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` La clausola all'interno del `when` blocco viene valutata solo se il valore specificato per `BucketName` è una stringa. Se il valore specificato per `BucketName` è referenziato nella `Parameters` sezione del modello, come illustrato nell'esempio seguente, la clausola all'interno del `when` blocco non viene valutata. ``` Parameters: S3BucketName: Type: String Resources: S3Bucket: Type: AWS::S3::Bucket Properties: BucketName: Ref: S3BucketName ... ``` ### Blocchi con regole denominate *È possibile assegnare un nome a un set di regole (set di regole) e quindi fare riferimento a questi blocchi di convalida modulari, denominati blocchi con regole *denominate, in altre regole*.* I blocchi con regole denominate assumono la forma seguente. ``` rule [when ] { Guard_rule_1 Guard_rule_2 ... } ``` La `rule` parola chiave indica l'inizio del blocco di regole con nome. `rule name`è una stringa leggibile dall'uomo che identifica in modo univoco un blocco di regole con nome. È un'etichetta per il set di regole Guard che incapsula. In questo uso, il termine *regola Guard* include clausole, blocchi di query, blocchi e blocchi di regole denominate. `when` Il nome della regola può essere usato per fare riferimento al risultato della valutazione del set di regole che incapsula, il che rende riutilizzabili i blocchi con regole denominate. Il nome della regola fornisce inoltre un contesto sugli errori delle regole negli output e dei comandi. `validate` `test` Il nome della regola viene visualizzato insieme allo stato di valutazione del blocco (`PASS``FAIL`, o`SKIP`) nell'output di valutazione del file delle regole. Guarda l'esempio seguente. ``` # 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** ``` È inoltre possibile valutare i blocchi con regole denominate in modo condizionale specificando la `when` parola chiave seguita da una condizione dopo il nome della regola. Di seguito è riportato il `when` blocco di esempio discusso in precedenza in questo argomento. ``` rule checkBucketNameStringValue when Resources.S3Bucket.Properties.BucketName is_string { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Utilizzando blocchi con regole denominate, il precedente può anche essere scritto come segue. ``` rule checkBucketNameIsString { Resources.S3Bucket.Properties.BucketName is_string } rule checkBucketNameStringValue when checkBucketNameIsString { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Puoi riutilizzare e raggruppare blocchi con regole denominate con altre regole di Guard. Di seguito sono riportati alcuni esempi. ``` 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 ... } ``` ## Utilizzo delle funzioni integrate AWS CloudFormation Guard fornisce funzioni integrate che puoi utilizzare nelle tue regole per eseguire operazioni come la manipolazione di stringhe, l'analisi JSON e la conversione dei tipi di dati. Le funzioni sono supportate solo tramite l'assegnazione a una variabile. ### Funzioni chiave `json_parse(json_string)` Analizza le stringhe JSON in linea da un modello. Dopo l'analisi, è possibile valutare le proprietà dell'oggetto risultante. `count(collection)` Restituisce il numero di elementi in cui viene risolta una query. `regex_replace(base_string, regex_to_extract, regex_replacement)` Sostituisce parti di una stringa utilizzando espressioni regolari. Per un elenco completo delle funzioni disponibili, tra cui la manipolazione delle stringhe, le operazioni di raccolta e le funzioni di conversione dei tipi di dati, consulta la [documentazione sulle funzioni nel repository](https://github.com/aws-cloudformation/cloudformation-guard/blob/main/docs/FUNCTIONS.md) Guard GitHub .