Rego 102: Abfragen mit AND/OR und benutzerdefinierten Meldungen kombinieren

Diese Blogpost-Reihe bietet eine verständliche Einführung in Rego, die Policy-Sprache der Entwickler der Open Policy Agent (OPA)-Engine. Wenn Sie noch am Anfang stehen und Rego-Policies als Code schreiben möchten, sind Sie hier genau richtig.

In dieser dreiteiligen Reihe behandeln wir folgende Themen:

• Teil 1: Rego für Einsteiger: Einführung in Rego

• Teil 2 (dieser Teil!): Rego-Syntax für Fortgeschrittene

• Teil 3: Werttypen und Regeln

Zur Erinnerung: Rego ist eine deklarative Abfragesprache von den Entwicklern des Open Policy Agent (OPA)-Frameworks. Die Cloud Native Computing Foundation (CNCF) nahm OPA im April 2019 als gehostetes Projekt auf Inkubationsebene auf. 2021 schloss OPA die Inkubationsphase ab.

Mit Rego schreiben Sie Policies als Code. Dabei kommen Programmierpraktiken wie Versionskontrolle und modularer Aufbau zum Einsatz, um Cloud- und Infrastructure-as-Code-Ressourcen (IaC) auszuwerten. OPA ist die Engine, die in Rego geschriebenen Policy-Code auswertet. Snyk verwendet die Rego-Sprache für benutzerdefinierte Regeln.

Rückblick auf Teil 1

In Teil 1 dieser Blogpost-Reihe haben wir erklärt, dass eine Rego-Regel eine bedingte Zuweisung ist. Eine Regel fragt die Eingabe nach einer passenden Bedingung ab. Wird eine Übereinstimmung gefunden, wird einer Variablen ein Wert zugewiesen.

Eine Regel können Sie so lesen:

1THIS VARIABLE    :=	HAS THIS VALUE {
2    IF THESE CONDITIONS ARE MET
3}

Hier ist das Beispiel, das wir verwendet haben. Es beschreibt eine Unternehmens-Policy: Nur Alice, eine Netzwerkadministratorin, darf virtuelle Netzwerke im Prod-Konto erstellen und löschen.

1allow := true {
2  input.user == "alice"
3}

OPA wertet ein JSON- oder YAML-Eingabedokument anhand einer Regel aus, um eine Policy-Entscheidung zu treffen. Das folgende Eingabedokument enthält den aktuell angemeldeten Benutzer:

1{
2  "user": "alice"
3}

Wenn Sie mit OPA die Eingabe anhand dieser Regel auswerten, findet OPA eine Übereinstimmung für die Abfrage input.user == "alice". Daher erhält die Variable im Regelkopf, allow, den Wert aus dem Regelkopf: true. Das folgende Ergebnis belegt dies:

1{
2  "allow": true
3}

OPA hat entschieden, dass Alice, die aktuell angemeldete Benutzerin, virtuelle Netzwerke im Prod-Konto erstellen und löschen darf. Die Eingabe ist mit der Regel konform.

AND und OR

Bisher haben wir nur Regeln mit einer einzelnen Abfrage gezeigt. Eine Regel kann auch mehrere Abfragen enthalten. In diesem Fall stehen die Abfragen für mehrere Bedingungen, die alle erfüllt sein müssen, damit einer Variablen ein Wert zugewiesen wird. Implizit gilt ein AND – „Diese Bedingung muss erfüllt sein UND diese Bedingung muss erfüllt sein.“

In der folgenden Regel müssen beispielsweise sowohl input.user == "alice" UND input.environment == "prod" wahr sein, damit der Variablen allow der Wert true zugewiesen wird:

1allow := true {
2  input.user == "alice"
3  input.environment == "prod"
4}

In manchen Fällen ist ein OR passender. Ein OR lässt sich darstellen, indem Sie in mehreren Regeln denselben Regelkopf verwenden:

1allow = true {
2  input.user == "alice"
3}
4
5allow = true {
6  input.user == "bob"
7}

Diese Regeln lassen sich wie folgt lesen:

allow ist true, wenn user "alice" ist ODER wenn user "bob" ist.

Technisch gesehen bilden die Regeln zusammen eine einzige Regel, da beide denselben Regelkopf haben. Weil Sie diese Regel in mehreren Schritten definieren, wird sie als inkrementelle Regel bezeichnet.

Sie können den zweiten Regelkopf auch weglassen und die Regelkörper zusammenführen. Die obige Regel lässt sich kürzer so schreiben:

1allow = true {
2  input.user == "alice"
3} {
4  input.user == "bob"
5}

Vielleicht fragen Sie sich, warum wir den Unifikationsoperator = statt des Zuweisungsoperators := verwendet haben. Das liegt daran, dass Variablen in Rego unveränderlich sind. Auch wenn Regeln mit demselben Regelkopf als eine inkrementelle Regel behandelt werden, würden Sie bei Verwendung des Zuweisungsoperators dieselbe Variable effektiv mehrfach „zuweisen“ – und das ist in Rego nicht erlaubt. Stattdessen verwenden wir im Regelkopf den Unifikationsoperator, weil er mehrere Regeln mit demselben Namen vereinheitlicht.

Wenn Sie sich nur schwer merken können, wann welcher Operator im Regelkopf verwendet wird, gibt es dank Standardwerten und etwas syntaktischer Vereinfachung eine einfachere Möglichkeit.

Standardwerte in Regelköpfen

Der Standardwert einer Variablen im Regelkopf ist true. Deshalb bietet Rego hier eine syntaktische Vereinfachung: Weist eine Regel der Variablen den Wert true zu, können Sie := true im Regelkopf weglassen.

Das bedeutet, dass diese AND-Regel …

1allow := true {
2  input.user == "alice"
3  input.environment == "prod"
4}

… dasselbe ist wie diese AND-Regel:

1allow {
2  input.user == "alice"
3  input.environment == "prod"
4}

Und genauso ist diese OR-Regel …

1allow = true {
2  input.user == "alice"
3} {
4  input.user == "bob"
5}

… dasselbe wie diese OR-Regel:

1allow {
2  input.user == "alice"
3} {
4  input.user == "bob"
5}

„Klasse“!

Das Schlüsselwort default

Wie wir in Teil 1 besprochen haben, wird der Variablen im Regelkopf der dort angegebene Wert nicht zugewiesen, wenn die Eingabe keine Übereinstimmung für eine Regelabfrage enthält.

Zur Veranschaulichung kehren wir zu unserer Beispielregel zurück: Nur Alice, eine Netzwerkadministratorin, darf virtuelle Netzwerke im Prod-Konto erstellen und löschen.

1allow := true {
2  input.user == "alice"
3}

Nehmen wir an, wir haben ein Eingabedokument, in dem Bob als aktuell angemeldeter Benutzer angegeben ist:

1{
2  "user": "bob"
3}

Da input.user nicht "alice" ist, findet OPA bei der Auswertung der Regel anhand der Eingabe keine Übereinstimmung. Daher erhält allow nicht den Wert true, und das Ergebnis der Auswertung ist eine leere Menge:

1{}

In diesem Fall sagen wir, dass der Wert von allow undefiniert ist. Wenn OPA Eingaben zur Auswertung einer Regel abfragt, gibt es nur passende Werte zurück. Gibt es keinen passenden Wert, gibt es nichts zurück – daher die leere Menge.

Was, wenn wir möchten, dass OPA false zurückgibt, wenn allow nicht ausdrücklich true ist? Mit dem Schlüsselwort default können wir einen Standardwert festlegen. Das bedeutet: Wenn eine Regel nicht ausdrücklich zu true ausgewertet wird, gibt sie einen bestimmten Wert zurück (in diesem Fall false), statt eine leere Ergebnismenge zurückzugeben. Dazu schreiben wir eine zusätzliche Regel, die ebenfalls allow verwendet:

1default allow = false

Wenn OPA nun feststellt, dass input.user nicht "alice" ist, ergibt die Auswertung von allow keine leere Menge. Stattdessen erhält die Variable den Standardwert, den wir als false festgelegt haben:

1{
2  "allow": false
3}

Beachten Sie: Wenn Sie das Schlüsselwort default angeben, verwenden Sie sowohl in der Regel, in der Sie den Standardwert definieren, als auch in der Regel für die bedingte Zuweisung den Unifikationsoperator = statt des Zuweisungsoperators :=. Auch hier gilt: Variablen sind unveränderlich. Verwenden Sie den Zuweisungsoperator, weisen Sie dieselbe Variable mehrfach zu – das lässt Rego nicht zu. Verwenden Sie stattdessen den Unifikationsoperator:

1default allow = false
2
3allow = true {
4  input.user == "alice"
5}

Natürlich können Sie auch die zuvor beschriebene syntaktische Vereinfachung nutzen und = true in der Regel mit der bedingten Zuweisung weglassen. Das ist völlig in Ordnung und möglicherweise einfacher, weil Sie sich nicht merken müssen, welcher Operator für die bedingte Zuweisung zu verwenden ist:

1default allow = false
2
3allow {
4  input.user == "alice"
5}

Benutzerdefinierte Meldungen

Manchmal möchten Sie statt eines einfachen Ergebnisses wie bestanden oder nicht bestanden – true oder false/undefiniert – mehrere Meldungen zurückgeben. Dafür verwenden Sie den Regelkopf deny[msg] und weisen der Variablen msg die gewünschte Meldung zu. Die folgende Regel prüft, ob der Benutzer nicht Alice ist. Falls nicht, weist sie msg die Zeichenfolge „User is denied access“ zu, die dann der Menge deny hinzugefügt wird (mehr zu Mengen erfahren Sie in Teil 3):

1deny[msg] {
2  input.user != "alice"
3  msg := "User is denied access"
4}

Um dies zu testen, nehmen wir an, unser Eingabedokument enthält den Namen des aktuell angemeldeten Benutzers:

1{
2	"user": "bob"
3}

Wenn wir die Regel anhand der obigen Eingabe mit dem Rego Playground von OPA oder dem Befehl opa eval -i input.json -d check_user.rego "data.rules.check_user" --format pretty auswerten (Anweisungen finden Sie in unserem Blogpost zu Teil 1), sieht das Ergebnis so aus:

1{
2  "deny": [
3	"User is denied access"
4  ]
5}

Was passiert hier? Wir erstellen eine Mengenregel, auf die wir in unserem nächsten Blogpost dieser Reihe zurückkommen. Für den Moment genügt es zu wissen, dass wir statt eines einzelnen Ergebnisses – true, false oder undefiniert – eine Menge von Meldungen zurückgeben, die der Variable deny zugewiesen sind. In Rego ist eine Menge eine ungeordnete Liste eindeutiger Elemente, etwa Ganzzahlen { 1, 2, 3 }, Zeichenfolgen { "alice", "bob", "carlotta" } oder sogar andere Mengen { { 1, 2}, {3, 4} }. Sie können eine Menge aus jedem unterstützten Rego-Typ bilden und sogar verschiedene Typen in einer Menge kombinieren.

In unserer Beispielregel ist jedes Element der Menge deny eine Zeichenfolge mit einer Meldung. Für dieses Eingabedokument gibt es nur ein Element in der Menge, es können aber auch mehr sein. Ein Beispiel dazu zeigen wir später in diesem Blogpost.

Was, wenn wir in der Meldung weitere Informationen zurückgeben möchten? Mit der integrierten Funktion sprintf können wir den Wert des Felds input.user anzeigen, der das Ergebnis deny ausgelöst hat:

1deny[msg] {
2  input.user != "alice"
3  msg := sprintf("User %v is denied access", [input.user])
4}

Die Funktion sprintf nimmt zwei Argumente entgegen: eine Zeichenfolge und ein Array mit Werten. In diesem Fall enthält das Array nur ein Element: die Zeichenfolge input.user. Im ersten Argument verwenden wir %v als Platzhalter. Bei der Auswertung der Regel wird er durch den Wert im Array ersetzt.

Wenn wir die Regel nun mit der folgenden Eingabe auswerten …

1{
2	"user": "bob"
3}

… sehen wir dieses Ergebnis:

1{
2  "deny": [
3    "User bob is denied access"
4  ]
5}

Das Schlüsselwort not

Sie können einen Ausdruck negieren, indem Sie ihm das Schlüsselwort not voranstellen. Dadurch erhält er die gegenteilige Bedeutung. Meistens verwenden Sie dies in einer Abfrage, um anzugeben, dass eine Eigenschaft in der Eingabe fehlt. Diese Abfrage etwa:

1input.tags.environment

… bedeutet: „Das Eingabedokument enthält die Eigenschaft tags.environment, und ihr Wert ist nicht false.“ Diese Abfrage dagegen:

1not input.tags.environment

… bedeutet: „Das Eingabedokument enthält keine Eigenschaft tags.environment, oder tags.environment ist auf false gesetzt.“ Es gibt keine Überschneidung und keinen Mittelweg: Ein Ausdruck und seine Umkehrung schließen sich gegenseitig aus.

Hier ist eine Beispielregel, die true an deny zuweist, wenn der Eingabe das Tag department fehlt:

1deny {
2  not input.tags.department
3}

Verwenden wir diese Eingabe:

1{
2  "tags": {
3    "environment": "staging"
4  }
5}

Würden wir diese Eingabe anhand der obigen Regel auswerten, würden wir sehen, dass deny true zurückgibt, weil die erforderliche Eigenschaft department fehlt:

1{
2  "deny": true
3}

Eine Beispielregel mit OPA auswerten

Probieren wir die in diesem Blogpost besprochenen Konzepte aus und werten eine Beispielregel aus. Wie in Teil 1 konzentrieren wir uns auf zwei Möglichkeiten, mit OPA zu arbeiten:

• Den Rego Playground verwenden

• Das OPA-Kommandozeilentool verwenden

Eine Anleitung zur Verwendung dieser Schnittstellen finden Sie in Teil 1.

Diesmal verwenden wir ein praxisnäheres Beispiel mit einem Kubernetes-Pod. Hier ist das JSON-Manifest, das wir als Eingabe verwenden:

1{
2  "apiVersion": "v1",
3  "kind": "Pod",
4  "metadata": {
5    "name": "nginx-demo",
6    "labels": {
7      "release" : "stable"
8    }
9  },
10  "spec": {
11    "containers": [
12      {
13        "name": "nginx",
14        "image": "nginx:1.14.2",
15        "ports": [
16          {
17            "containerPort": 80
18          }
19        ]
20      }
21    ]
22  }
23}

Und hier ist die Regel, anhand derer wir die Eingabe auswerten. Sie setzt die Unternehmens-Policy „Kubernetes-Pods müssen mit release und environment gekennzeichnet sein“ durch:

1deny[msg] {
2  input.kind == "Pod"
3  not input.metadata.labels.release
4  msg := sprintf("Pod %v is missing release label", [input.metadata.name])
5} {
6  input.kind == "Pod"
7  not input.metadata.labels.environment
8  msg := sprintf("Pod %v is missing environment label", [input.metadata.name])
9}

Diese Regel veranschaulicht einige der Konzepte, die wir in diesem Blogpost besprochen haben:

• deny[msg], um eine Menge benutzerdefinierter Meldungen statt true oder false/undefined zurückzugeben

• Die Regelstruktur kombiniert AND und OR:

  • Ablehnen, wenn es sich beim Kubernetes-Objekt um einen Pod handelt UND ihm das Release-Label fehlt ODER:

  • Ablehnen, wenn es sich beim Kubernetes-Objekt um einen Pod handelt UND ihm das Environment-Label fehlt

• Das Schlüsselwort not, um das Fehlen einer Eigenschaft zu prüfen

• Die Funktion sprintf, um eine Meldung mit dem Namen des nicht konformen Pods zurückzugeben

Damit Sie es einfacher haben, haben wir einen Playground mit diesen Inhalten vorbereitet: https://play.openpolicyagent.org/p/KNVK9kEvIT

Wenn Sie die Regel auswerten, indem Sie im Playground auf Evaluate klicken, oder lokal OPA mit einem Befehl wie opa eval -i input.json -d check_pod.rego "data.rules.check_pod" --format pretty ausführen, sehen Sie folgende Ausgabe:

1{
2  "deny": [
3    "Pod nginx-demo is missing environment label"
4  ]
5}

Wie wir sehen, entspricht der überprüfte Kubernetes-Pod nicht unserer Regel, da die Eingabe keine Eigenschaft labels.environment enthält.

Entfernen wir nun die Eigenschaft labels.release. Der Abschnitt labels der Eingabe sollte dann so aussehen:

1    "labels": {
2    }

Wenn Sie die Regel jetzt auswerten, sehen Sie, dass das deny-Set zwei Meldungen enthält:

1{
2  "deny": [
3    "Pod nginx-demo is missing environment label",
4    "Pod nginx-demo is missing release label"
5  ]
6}

Fügen wir der Eingabe schließlich sowohl eine Eigenschaft labels.release als auch eine Eigenschaft labels.environment hinzu, sodass sie so aussieht:

1    "labels": {
2      "release" : "stable",
3      "environment": "prod"
4    }

Was passiert, wenn wir die Regel erneut auswerten? Das deny-Set ist leer:

1{
2  "deny": []
3}

Das bedeutet, dass unser Pod regelkonform ist, da OPA keine Meldungen zum deny-Set hinzugefügt hat. Hurra!

Wie geht es weiter?

Kehren Sie zu unserem Blog zurück und lesen Sie Rego for Beginners Part 3. Darin beschäftigen wir uns mit Set-Regeln, Objektregeln, Funktionen und Iterationen.

In der Zwischenzeit finden Sie hier einige nützliche Ressourcen:

• OPA’s website

• Rego policy reference

• Rego Playground

• Using Rego as a generic policy language 

• Policy-as-Code mit OPA und Rego ermöglichen

• Five tips for using the Rego language for OPA

Wenn Sie Rego verwenden möchten, um benutzerdefinierte Regeln für Snyk IaC zu schreiben, finden Sie hier unsere Dokumentation. Zusätzlich zu den integrierten Sicherheits- und Compliance-Regelsätzen von Snyk ermöglichen Ihnen benutzerdefinierte IaC+-Regeln, Sicherheitskontrollen für Ihren gesamten SDLC festzulegen.

IaC+ bietet Ihnen eine zentrale Übersicht über Ihre Konfigurationsprobleme und ermöglicht deren Kontrolle – vom Code bis zur Cloud. Dafür stehen Ihnen eine Benutzeroberfläche für Probleme, ein Regelsatz und eine Policy-Engine zur Verfügung, die IDE, SCM, CLI, CI/CD, Terraform Cloud und bereitgestellte Cloud-Umgebungen wie AWS, Azure und Google Cloud abdecken.