Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # AWS CloudFormation Guard Regeln schreiben In AWS CloudFormation Guard sind *Regeln Regeln*. policy-as-code Sie schreiben Regeln in der domänenspezifischen Sprache (DSL) von Guard, anhand derer Sie Ihre Daten im JSON- oder YAML-Format validieren können. *Regeln bestehen aus Klauseln.* Sie können Regeln, die mit Guard DSL geschrieben wurden, in Klartextdateien speichern, die eine beliebige Dateierweiterung verwenden. *Sie können mehrere Regeldateien erstellen und sie als Regelsatz kategorisieren.* Regelsätze ermöglichen es Ihnen, Ihre Daten im JSON- oder YAML-Format anhand mehrerer Regeldateien gleichzeitig zu validieren. **Topics** + [Klauseln](#clauses) + [Verwenden von Abfragen in Klauseln](#clauses-queries) + [Verwenden von Operatoren in Klauseln](#clauses-operators) + [Verwenden von benutzerdefinierten Nachrichten in Klauseln](#clauses-custom-messages) + [Klauseln kombinieren](#combining-clauses) + [Blöcke mit Guard-Regeln verwenden](#blocks) + [Verwenden von integrierten Funktionen](#built-in-functions) + [Definition und Filterung von Guard-Abfragen](query-and-filtering.md) + [Zuweisen und Referenzieren von Variablen in Guard-Regeln](variables.md) + [Blöcke mit benannten Regeln verfassen in AWS CloudFormation Guard](named-rule-block-composition.md) + [Klauseln schreiben, um kontextsensitive Bewertungen durchzuführen](context-aware-evaluations.md) ## Klauseln Klauseln sind boolesche Ausdrücke, die entweder true (`PASS`) oder false () ergeben. `FAIL` Klauseln verwenden entweder binäre Operatoren, um zwei Werte zu vergleichen, oder unäre Operatoren, die auf einen einzelnen Wert angewendet werden. **Beispiele für unäre Klauseln** Die folgende unäre Klausel bewertet, ob die Sammlung leer ist. `TcpBlockedPorts` ``` InputParameters.TcpBlockedPorts not empty ``` Die folgende unäre Klausel bewertet, ob es sich bei der `ExecutionRoleArn` Eigenschaft um eine Zeichenfolge handelt. ``` Properties.ExecutionRoleArn is_string ``` **Beispiele für Binärklauseln** Die folgende Binärklausel bewertet unabhängig von der Groß- und Kleinschreibung`encrypted`, ob die `BucketName` Eigenschaft die Zeichenfolge enthält. ``` Properties.BucketName != /(?i)encrypted/ ``` Die folgende Binärklausel bewertet, ob die `ReadCapacityUnits` Eigenschaft kleiner oder gleich 5.000 ist. ``` Properties.ProvisionedThroughput.ReadCapacityUnits <= 5000 ``` ### Syntax für das Schreiben von Guard-Regelklauseln ``` [query|value literal] [custom message] ``` ### Eigenschaften von Guard-Regelklauseln `query` Ein durch Punkte (`.`) getrennter Ausdruck, der geschrieben wurde, um hierarchische Daten zu durchqueren. Abfrageausdrücke können Filterausdrücke enthalten, die auf eine Teilmenge von Werten abzielen. Abfragen können Variablen zugewiesen werden, sodass Sie sie einmal schreiben und an anderer Stelle in einem Regelsatz auf sie verweisen können, wodurch Sie auf Abfrageergebnisse zugreifen können. Weitere Hinweise zum Schreiben und Filtern von Abfragen finden Sie unter[Abfragen definieren und filtern](query-and-filtering.md). *Erforderlich*: Ja `operator` Ein unärer oder binärer Operator, mit dessen Hilfe der Status der Abfrage überprüft werden kann. Die linke Seite (LHS) eines binären Operators muss eine Abfrage sein, und die rechte Seite (RHS) muss entweder eine Abfrage oder ein Werteliteral sein. *Unterstützte binäre Operatoren*: `==` (Gleich) \$1 `!=` (Ungleich) \$1 `>` (Größer als) \$1 `>=` (Größer als oder gleich) \$1 (Kleiner als) \$1 `<` (Kleiner als) \$1 `<=` (Kleiner als oder gleich) \$1 `IN` (In einer Liste der Form [x, y, z] *Unterstützte unäre Operatoren*: `exists` \$1 `empty` \$1 `is_string` \$1 \$1 `is_list` \$1 `is_struct` `not(!)` *Erforderlich*: Ja `query|value literal` Eine Abfrage oder ein unterstütztes Werteliteral wie `string` oder. `integer(64)` *Unterstützte Werteliterale*: + Alle primitiven Typen:`string`,`integer(64)`,`float(64)`,`bool`, `char` `regex` + Alle speziellen Bereichstypen zum Ausdrücken von`integer(64)`,`float(64)`, oder `char` Bereichen, ausgedrückt als: + `r[, ]`, was in einen beliebigen Wert übersetzt wird`k`, der den folgenden Ausdruck erfüllt: `lower_limit <= k <= upper_limit` + `r[, `), was in einen beliebigen Wert übersetzt wird`k`, der den folgenden Ausdruck erfüllt: `lower_limit <= k < upper_limit` + `r(, ]`, was in einen beliebigen Wert übersetzt wird`k`, der den folgenden Ausdruck erfüllt: `lower_limit < k <= upper_limit` + `r(, ),`was zu einem beliebigen Wert übersetzt wird`k`, der den folgenden Ausdruck erfüllt: `lower_limit < k < upper_limit` + Assoziative Arrays (Maps) für verschachtelte Schlüsselwert-Strukturdaten. Beispiel: `{ "my-map": { "nested-maps": [ { "key": 10, "value": 20 } ] } }` + Arrays primitiver Typen oder assoziativer Arraytypen *Erforderlich*: Bedingt; erforderlich, wenn ein binärer Operator verwendet wird. `custom message` Eine Zeichenfolge, die Informationen über die Klausel bereitstellt. Die Meldung wird in den ausführlichen Ausgaben der `test` Befehle `validate` und angezeigt und kann hilfreich sein, um die Regelauswertung hierarchischer Daten zu verstehen oder zu debuggen. *Required*: No ## Verwenden von Abfragen in Klauseln Hinweise zum Schreiben von Abfragen finden Sie unter [Abfragen definieren und filtern](query-and-filtering.md) und[Zuweisen und Referenzieren von Variablen in Guard-Regeln](variables.md). ## Verwenden von Operatoren in Klauseln Im Folgenden finden Sie CloudFormation Beispielvorlagen, `Template-1` und`Template-2`. Zur Veranschaulichung der Verwendung unterstützter Operatoren beziehen sich die Beispielabfragen und Klauseln in diesem Abschnitt auf diese Beispielvorlagen. **Vorlagen-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 ``` **Vorlage-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 ``` ### Beispiele für Klauseln, die unäre Operatoren verwenden + `empty`— Prüft, ob eine Sammlung leer ist. Sie können damit auch überprüfen, ob eine Abfrage Werte in hierarchischen Daten enthält, da Abfragen zu einer Sammlung führen. Sie können damit nicht überprüfen, ob für Abfragen mit Zeichenkettenwerten eine leere Zeichenfolge (`""`) definiert ist. Weitere Informationen finden Sie unter [Abfragen definieren und filtern](query-and-filtering.md). Die folgende Klausel prüft, ob für die Vorlage eine oder mehrere Ressourcen definiert sind. Sie wird als ausgewertet, `PASS` weil eine Ressource mit der logischen ID in `Template-1` definiert `S3Bucket` ist. ``` Resources !empty ``` Die folgende Klausel prüft, ob ein oder mehrere Tags für die `S3Bucket` Ressource definiert sind. Sie wird als ausgewertet, `PASS` weil `S3Bucket` zwei Tags für die `Tags` Eigenschaft in `Template-1` definiert sind. ``` Resources.S3Bucket.Properties.Tags !empty ``` + `exists`— Prüft, ob jedes Vorkommen der Abfrage einen Wert hat und anstelle von `!= null` verwendet werden kann. Die folgende Klausel prüft, ob die `BucketEncryption` Eigenschaft für definiert ist`S3Bucket`. Sie wird als ausgewertet, `PASS` weil für `S3Bucket` in `Template-1` definiert `BucketEncryption` ist. ``` Resources.S3Bucket.Properties.BucketEncryption exists ``` **Anmerkung** Die `not exists` Prüfungen `empty` und geben beim `true` Durchlaufen der Eingabedaten auf fehlende Eigenschaftsschlüssel zurück. Wenn der `Properties` Abschnitt beispielsweise in der Vorlage für nicht definiert ist`S3Bucket`, wird die Klausel wie folgt `Resources.S3Bucket.Properties.Tag empty` ausgewertet. `true` Bei den `empty` Prüfungen `exists` und wird der JSON-Zeigerpfad innerhalb des Dokuments in den Fehlermeldungen nicht angezeigt. Beide Klauseln weisen häufig Abruffehler auf, sodass diese Traversalinformationen nicht beibehalten werden. + `is_string`— Überprüft, ob jedes Vorkommen der Abfrage vom Typ ist. `string` Die folgende Klausel prüft, ob ein Zeichenkettenwert für die `BucketName` Eigenschaft der `S3Bucket` Ressource angegeben ist. Sie wird als ausgewertet, `PASS` weil der Zeichenkettenwert für `BucketName` in `Template-1` angegeben `"MyServiceS3Bucket"` ist. ``` Resources.S3Bucket.Properties.BucketName is_string ``` + `is_list`— Prüft, ob jedes Vorkommen der Abfrage `list` vom Typ ist. Die folgende Klausel prüft, ob eine Liste für die `Tags` Eigenschaft der `S3Bucket` Ressource angegeben ist. Sie wird als ausgewertet, `PASS` weil zwei Schlüssel-Wert-Paare für in angegeben sind. `Tags` `Template-1` ``` Resources.S3Bucket.Properties.Tags is_list ``` + `is_struct`— Prüft, ob es sich bei jedem Vorkommen der Abfrage um strukturierte Daten handelt. Die folgende Klausel prüft, ob strukturierte Daten für die `BucketEncryption` Eigenschaft der `S3Bucket` Ressource angegeben sind. Sie `BucketEncryption` wird als ausgewertet, `PASS` weil sie mit dem `ServerSideEncryptionConfiguration` Eigenschaftstyp *(object)* in `Template-1` angegeben wurde. ``` Resources.S3Bucket.Properties.BucketEncryption is_struct ``` **Anmerkung** Um den umgekehrten Zustand zu überprüfen, können Sie den Operator (` not !`) zusammen mit den Operatoren `is_string``is_list`, und `is_struct` verwenden. ### Beispiele für Klauseln, die binäre Operatoren verwenden Die folgende Klausel prüft unabhängig von der Groß- und Kleinschreibung, ob der für die `BucketName` Eigenschaft der `S3Bucket` Ressource in angegebene Wert die Zeichenfolge `Template-1` `encrypt` enthält. Dies ergibt, `PASS` weil der angegebene Bucket-Name die Zeichenfolge `"MyServiceS3Bucket"` `encrypt` nicht enthält. ``` Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ ``` Die folgende Klausel prüft, ob der für die `Size` Eigenschaft der `NewVolume` Ressource in angegebene Wert innerhalb eines bestimmten Bereichs `Template-2` liegt: 50 <= `Size` <= 200. Sie wird als ausgewertet, `PASS` weil für angegeben `100` ist. `Size` ``` Resources.NewVolume.Properties.Size IN r[50,200] ``` Die folgende Klausel überprüft, ob der für die `VolumeType` Eigenschaft der `NewVolume` Ressource in angegebene Wert`io1`,`io2`, oder `Template-2` `gp3` ist. Sie wird als ausgewertet, `PASS` weil für `NewVolume` angegeben `io1` ist. ``` Resources.NewVolume.Properties.NewVolume.VolumeType IN [ 'io1','io2','gp3' ] ``` **Anmerkung** Die Beispielabfragen in diesem Abschnitt veranschaulichen die Verwendung von Operatoren, die Ressourcen mit logischem IDs `S3Bucket` und `NewVolume` verwenden. Ressourcennamen sind häufig benutzerdefiniert und können in einer IaC-Vorlage (Infrastructure as Code) beliebig benannt werden. Um eine Regel zu schreiben, die generisch ist und für alle in der Vorlage definierten `AWS::S3::Bucket` Ressourcen gilt, ist die am häufigsten verwendete Abfrageform. `Resources.*[ Type == ‘AWS::S3::Bucket’ ]` Weitere Informationen zur Verwendung finden Sie unter[Abfragen definieren und filtern](query-and-filtering.md). Weitere Informationen finden Sie im Verzeichnis mit den [Beispielen](https://github.com/aws-cloudformation/cloudformation-guard/tree/main/guard-examples) im `cloudformation-guard` GitHub Repository. ## Verwenden von benutzerdefinierten Nachrichten in Klauseln Im folgenden Beispiel `Template-2` enthalten Klauseln für eine benutzerdefinierte Nachricht. ``` 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' ] <> ``` ## Klauseln kombinieren In Guard wird jede Klausel, die in eine neue Zeile geschrieben wird, implizit mit der nächsten Klausel kombiniert, indem Konjunktion (`and`Boolesche Logik) verwendet wird. Sehen Sie sich das folgende Beispiel an. ``` # clause_A ^ clause_B ^ clause_C clause_A clause_B clause_C ``` Sie können Disjunktion auch verwenden, um eine Klausel mit der nächsten Klausel zu kombinieren, indem Sie `or|OR` am Ende der ersten Klausel angeben. ``` [query|value literal] [custom message] [or|OR] ``` In einer Guard-Klausel werden Disjunktionen zuerst ausgewertet, gefolgt von Konjunktionen. Guard-Regeln können als Konjunktion von Disjunktionen von Klauseln (und `and|AND` von `or|OR` s) definiert werden, die entweder als () oder `true` (`PASS`) ausgewertet werden. `false` `FAIL` Dies ähnelt der [konjunktiven Normalform](https://en.wikipedia.org/wiki/Conjunctive_normal_form). Die folgenden Beispiele veranschaulichen die Reihenfolge der Bewertungen von Klauseln. ``` # (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 ``` Alle Klauseln, die auf dem Beispiel basieren, `Template-1` können mithilfe von Konjunktion kombiniert werden. Sehen Sie sich das folgende Beispiel an. ``` 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 ``` ## Blöcke mit Guard-Regeln verwenden Blöcke sind Kompositionen, die aus einer Reihe verwandter Klauseln, Bedingungen oder Regeln Ausführlichkeit und Wiederholungen entfernen. Es gibt drei Arten von Blöcken: + Blöcke abfragen + `when`Blöcke + Blöcke mit benannten Regeln ### Blöcke abfragen Im Folgenden sind die Klauseln aufgeführt, die auf dem Beispiel `Template-1` basieren. Die Konjunktion wurde verwendet, um die Klauseln zu kombinieren. ``` 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 ``` Teile des Abfrageausdrucks in jeder Klausel werden wiederholt. Sie können die Zusammensetzbarkeit verbessern und Ausführlichkeit und Wiederholungen aus einer Reihe verwandter Klauseln mit demselben anfänglichen Abfragepfad entfernen, indem Sie einen Abfrageblock verwenden. Derselbe Satz von Klauseln kann wie im folgenden Beispiel geschrieben werden. ``` Resources.S3Bucket.Properties { BucketName is_string BucketName != /(?i)encrypt/ BucketEncryption exists BucketEncryption is_struct Tags is_list Tags !empty } ``` In einem Abfrageblock legt die Abfrage, die dem Block vorausgeht, den Kontext für die Klauseln innerhalb des Blocks fest. Weitere Hinweise zur Verwendung von Blöcken finden Sie unter[Blöcke mit benannten Regeln verfassen](named-rule-block-composition.md). ### `when`Blöcke Sie können Blöcke bedingt auswerten, indem Sie `when` Blöcke verwenden, die die folgende Form haben. ``` when { Guard_rule_1 Guard_rule_2 ... } ``` Das `when` Schlüsselwort bezeichnet den Anfang des Blocks. `when` `condition`ist eine Guard-Regel. Der Block wird nur ausgewertet, wenn die Auswertung der Bedingung zu `true` (`PASS`) führt. Im Folgenden finden Sie einen `when` Beispielblock, der auf basiert`Template-1`. ``` when Resources.S3Bucket.Properties.BucketName is_string { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Die Klausel innerhalb des `when` Blocks wird nur ausgewertet, wenn es sich bei dem für angegebenen Wert um eine Zeichenfolge `BucketName` handelt. Wenn der für angegebene Wert im `Parameters` Abschnitt der Vorlage referenziert `BucketName` wird, wie im folgenden Beispiel gezeigt, wird die Klausel innerhalb des `when` Blocks nicht ausgewertet. ``` Parameters: S3BucketName: Type: String Resources: S3Bucket: Type: AWS::S3::Bucket Properties: BucketName: Ref: S3BucketName ... ``` ### Blöcke mit benannten Regeln Sie können einem Regelsatz (*Regelsatz*) einen Namen zuweisen und dann in anderen Regeln auf diese modularen Validierungsblöcke, sogenannte Blöcke *mit benannten Regeln*, verweisen. Blöcke mit benannten Regeln haben die folgende Form. ``` rule [when ] { Guard_rule_1 Guard_rule_2 ... } ``` Das `rule` Schlüsselwort bezeichnet den Anfang des Blocks mit benannten Regeln. `rule name`ist eine für Menschen lesbare Zeichenfolge, die einen Block mit benannten Regeln eindeutig identifiziert. Es ist eine Bezeichnung für den Guard-Regelsatz, den es kapselt. Bei dieser Verwendung umfasst der Begriff *Guard-Regel* Klauseln, Abfrageblöcke, Blöcke und Blöcke mit `when` benannten Regeln. Der Regelname kann verwendet werden, um auf das Auswertungsergebnis des Regelsatzes zu verweisen, den er kapselt, wodurch Blöcke mit benannten Regeln wiederverwendet werden können. Der Regelname bietet auch Kontext zu Regelfehlern in der Ausgabe und in den `validate` Befehlsausgaben. `test` Der Regelname wird zusammen mit dem Bewertungsstatus des Blocks (`PASS``FAIL`, oder`SKIP`) in der Bewertungsausgabe der Regeldatei angezeigt. Sehen Sie sich das folgende Beispiel an. ``` # 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** ``` Sie können Blöcke mit benannten Regeln auch bedingt auswerten, indem Sie das `when` Schlüsselwort gefolgt von einer Bedingung hinter dem Regelnamen angeben. Im Folgenden finden Sie den `when` Beispielblock, der bereits in diesem Thema behandelt wurde. ``` rule checkBucketNameStringValue when Resources.S3Bucket.Properties.BucketName is_string { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Unter Verwendung von Blöcken mit benannten Regeln kann der vorherige Abschnitt auch wie folgt geschrieben werden. ``` rule checkBucketNameIsString { Resources.S3Bucket.Properties.BucketName is_string } rule checkBucketNameStringValue when checkBucketNameIsString { Resources.S3Bucket.Properties.BucketName != /(?i)encrypt/ } ``` Sie können Blöcke mit benannten Regeln wiederverwenden und mit anderen Guard-Regeln gruppieren. Im Folgenden finden Sie einige Beispiele. ``` 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 ... } ``` ## Verwenden von integrierten Funktionen AWS CloudFormation Guard bietet integrierte Funktionen, die Sie in Ihren Regeln verwenden können, um Operationen wie Zeichenkettenmanipulation, JSON-Analyse und Datentypkonvertierung durchzuführen. Funktionen werden nur durch Zuweisung zu einer Variablen unterstützt. ### Die wichtigsten Funktionen `json_parse(json_string)` Analysiert Inline-JSON-Zeichenketten aus einer Vorlage. Nach dem Parsen können Sie die Eigenschaften des resultierenden Objekts auswerten. `count(collection)` Gibt die Anzahl der Elemente zurück, in die eine Abfrage aufgelöst wird. `regex_replace(base_string, regex_to_extract, regex_replacement)` Ersetzt Teile einer Zeichenfolge mithilfe regulärer Ausdrücke. Eine vollständige Liste der verfügbaren Funktionen, einschließlich Zeichenkettenmanipulation, Sammlungsoperationen und Funktionen zur Konvertierung von Datentypen, finden Sie in der [Dokumentation zu Funktionen](https://github.com/aws-cloudformation/cloudformation-guard/blob/main/docs/FUNCTIONS.md) im GitHub Guard-Repository.