Clausole Utilizzo di interrogazioni nelle clausole Utilizzo degli operatori nelle clausole Utilizzo di messaggi personalizzati nelle clausole Combinazione di clausole Usare i blocchi con le regole di Guard Utilizzo delle funzioni integrate

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.

Argomenti

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 stringaencrypted, 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> <operator> [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

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

Campo 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[<lower_limit>, <upper_limit>], che si traduce in qualsiasi valore k che soddisfi la seguente espressione: lower_limit <= k <= upper_limit
- r[<lower_limit>, <upper_limit>), che si traduce in qualsiasi valore k che soddisfi la seguente espressione: lower_limit <= k < upper_limit
- r(<lower_limit>, <upper_limit>], che si traduce in qualsiasi valore k che soddisfi la seguente espressione: lower_limit < k <= upper_limit
- r(<lower_limit>, <upper_limit>),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. Per 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.

Required: No

Utilizzo di interrogazioni nelle clausole

Per informazioni sulla scrittura di interrogazioni, vedere e. Definizione di interrogazioni e filtri Assegnazione e riferimento a variabili nelle regole di Guard

Utilizzo degli operatori nelle clausole

Di seguito sono riportati CloudFormation modelli di esempio eTemplate-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.

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 diS3Bucket, la clausola restituisce lo stesso risultatoResources.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_stringis_list, eis_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 stringaencrypt, 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 è io1io2, 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 i dettagli sull'utilizzo ed esplora la directory degli esempi 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' ] <<Allowed Volume Types are io1, io2, and 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> <operator> [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.

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

`when`blocchi

È possibile valutare i blocchi in modo condizionale utilizzando when i blocchi, che assumono la forma seguente.


  when <condition> {
       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 suTemplate-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 <rule name> [when <condition>] {
    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 (PASSFAIL, oSKIP) 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 Guard GitHub .

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Prerequisiti e panoramica per l'utilizzo delle regole Guard

Definizione di interrogazioni e filtri

AWS CloudFormation Guard Regole di scrittura

Argomenti

Clausole

Sintassi per scrivere le clausole delle regole di Guard

Proprietà delle clausole delle regole Guard

Utilizzo di interrogazioni nelle clausole

Utilizzo degli operatori nelle clausole

Esempi di clausole che utilizzano operatori unari

Nota

Nota

Esempi di clausole che utilizzano operatori binari

Nota

Utilizzo di messaggi personalizzati nelle clausole

Combinazione di clausole

Utilizzo di blocchi con regole Guard

Blocchi di query

whenblocchi

Blocchi con regole denominate

Utilizzo delle funzioni integrate

Funzioni chiave

`when`blocchi