Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Eine Richtlinie, die an dem einen Blatt ansetzt, das der Autor geschrieben hat

Dieses Beispiel vermittelt eine Hausregel und die Tatsache, die sie ausdrückbar macht:

Ein Slot für Zugangsdaten darf befüllt werden. Er darf nicht befüllt werden, indem das Material in den eigenen Quelltext des Workspace geschrieben wird.

Zwei Releases, eine Variable auseinander: dieselbe verwaltete Datenbank, derselbe erforderliche Slot für Zugangsdaten, befüllt von zwei verschiedenen Features — eines bindet der Entwickler im Aggregate an, das andere bindet der Betreiber im Release an. Eine vom Betreiber verfasste Richtlinie weist das eine zurück und lässt das andere zu. Was das Paar lohnend macht, ist, dass beide Anbindungen geheimes Material verarbeiten — daher lässt sich die Regel nicht gegen die Frage „Ist diese Anbindung sensibel?“ schreiben, und die Kontroll-Richtlinie unten zeigt, was passiert, wenn Sie es versuchen.

Alles außer zwei Richtliniendateien stammt aus dem Katalog der Standardbibliothek, einschließlich der Governance-Plugin-Entität.

Der Slot und die beiden Features, die ihn befüllen können

core/datastore/mariadb deklariert einen erforderlichen Slot für Zugangsdaten:

featuresSchema:
root_password:
required: true
sensitive: true
inject: []
description: Root database password. Recipe controls delivery (Black-Box).

sensitive: true ist dort eine Aussage über den Bindungspunkt und nicht über eine bestimmte Befüllung: Was auch immer diesen Slot bindet, verarbeitet geheimes Material. inject: [] schließt die Auslieferung — das Recipe entscheidet, wohin die Zugangsdaten gehen, und der Entwickler gibt es nicht vor.

Zwei Features der Standardbibliothek binden diesen Slot, und sie bilden gegensätzliche Lebenszyklen von Zugangsdaten ab:

Featurewem das Material gehörtwas eine Anbindung verfasst
core/secret-valueein Autor stellt es bereitzwei Blätter in values — siehe unten
core/generated-secretdie Ziel-Engine richtet es ein und rotiert esnichts; es deklariert keine values

core/secret-value deklariert seine beiden Blätter asymmetrisch, und die Asymmetrie ist der ganze Angelpunkt dieses Beispiels:

values:
origin: { type: string, sensitive: true }
key: { type: string, required: true, default: "value" }

origin trägt das Material und ist als sensibel deklariert. key ist ein Auslieferungsname und bleibt bewusst unmarkiert — ein Schlüssel benennt, wo Material liegt, statt das Material zu sein, und jedes Recipe, das dieses Feature implementiert, rendert ihn im Klartext.

core/generated-secret deklariert überhaupt keine values, daher gibt es für eine Anbindung nichts zu verfassen. Es ist das von der Engine verwaltete Pendant und keine schwächere Version derselben Sache: Es trägt dasselbe Label der Zugangsdatenfamilie, es bindet denselben Slot, und seine Recipes rendern nichts, weil die Zugangsdaten der Engine gehören, die das eigene Recipe der Komponente verwaltet.

Die beiden Releases

aggregate-authored.yaml bindet den Slot auf die vom Autor bereitgestellte Weise: Der Entwickler bindet die Zugangsdaten im Aggregate an, und die Anbindung verfasst beide Blätter:

features:
root_password:
type: core/secret-value
values:
key: MARIADB_ROOT_PASSWORD
origin: root-password-in-the-clear

Der delegierte Zweig bindet ihn auf die von der Engine verwaltete Weise, und diese Bindung liegt beim Betreiber: Ob die Engine die Zugangsdaten besitzt, folgt aus dem Recipe, das das Manifest wählt, daher bindet release-delegated.yaml core/generated-secret an seinem Eintrag für db an, und aggregate-delegated.yaml ist das verfasste Aggregate ohne seinen Block features::

components:
db:
features:
root_password:
type: core/generated-secret

Beide Releases teilen sich manifest.yaml, das alle drei Typen für das Terraform-Ziel bindet, daher unterscheiden sich die beiden nicht im Manifest:

components:
type:
core/datastore/mariadb:1.0.0: terraform/mariadb-rds:1.0.0
features:
type:
core/secret-value:1.0.0: terraform/variable-secret:1.0.0
core/generated-secret:1.0.0: terraform/generated-secret:1.0.0

Die Richtlinie

policy.rego, über den Build-Graphen angebunden:

package house.governance
import rego.v1
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
some leaf in attachment.sensitive_payload_leaves
msg := sprintf("%v: the %v credential carries declared-sensitive material in its payload at %v", [node_id, attachment_name, leaf])
}

sensitive_payload_leaves listet die Blätter auf, die die Payload dieser Anbindung trägt und deren Pfad das angebundene Feature als sensibel deklariert, jeweils als gepunkteten Pfad mit dem Präfix der Säule. Gelesen wird die Payload, die die Anbindung am Ende trägt, daher wird ein Blatt, das auf einem Wert steht, den das Schema des Feature als default deklariert, ebenso genannt wie eines, auf das ein Autor geschrieben hat. Zwei Konsequenzen, und das Beispiel hängt an beiden:

  • Ein Blatt erscheint nur dort, wo eine Deklaration es abdeckt — die Deklaration nennt dieses Blatt oder nennt ein Objekt, das es enthält, segmentweise über den gepunkteten Pfad abgeglichen. Nichts wird aus dem eigenen Text des Pfads gelesen, und kein Wert wird untersucht. Daher erscheint key, das in derselben Anbindung neben origin geschrieben ist, nie: Sein Feature deklariert nichts darüber.
  • Eine Anbindung, deren Payload auf einem deklarierten Blatt nichts trägt, trägt nichts zur Liste bei. Die Anbindung des delegierten Release trägt die Antwort für die gesamte Anbindung und überhaupt keine Liste pro Blatt, weil der Schlüssel bei der Übertragung weggelassen wird, wenn er leer wäre.

Die Anbindung steht in .aggrega-config.yaml an der Rolle ir-verdict, der Rolle, die den Build-Graphen erhält:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policy.rego

Eine Verdikt-Rolle gibt eine Annahme oder eine Zurückweisung zurück und sonst nichts. Sie kann diesen Build stoppen; sie kann das Aggregate nicht in Konformität umschreiben, weil der Pfad, der ein Verdikt weiterleitet, keine Möglichkeit hat, eines als Änderung anzuwenden. Ein Release, das die delegierte Form will, erhält sie, indem es das delegierte Feature anbindet — niemals dadurch, dass eine Richtlinie stillschweigend eines ersetzt.

Beide bauen

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # expected to fail
aggrega build --release release-delegated.yaml --auto-pull

--auto-pull füllt die Lockfile während des Builds; aggrega pull --release release-<arm>.yaml einmal vorab tut dasselbe und lässt spätere Builds ohne Flag laufen. Die gerenderte Ausgabe und die Lockfiles werden erzeugt, nicht mitgeliefert: Dieses Beispiel committet seine Eingaben und erzeugt alles andere neu.

Was zurückkommt

Das verfasste Release wird zurückgewiesen, und der Build endet mit 1. E0005 ist die Diagnose, die eine Zurückweisung durch eine Richtlinie trägt — siehe die Diagnosereferenz:

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential carries declared-sensitive material in its payload at values.origin
caused by: policy violation

Lesen Sie den Blattpfad. Die Payload der Anbindung trägt zwei Werte; die Zurückweisung nennt values.origin und erwähnt values.key nicht. Dieser einzelne Satz ist die Markierung pro Blatt bei der Arbeit — eine Anbindung, zwei Payload-Blätter, eine Deklaration, eine Zurückweisung.

Die Zurückweisung kommt außerdem, bevor etwas gerendert wird. Es wird überhaupt kein Verzeichnis dist/infra-authored/ angelegt, daher gibt es keinen teilweisen Artefaktbaum aufzuräumen und nichts auf der Festplatte, das ein späterer Schritt für Ausgabe halten könnte.

Das delegierte Release wird gebaut, endet mit 0 und schreibt zwei Dateien. dist/infra-delegated/terraform/aggrega.modules.tf, die Root-Konfiguration der Boundary:

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "db" {
source = "./modules/db"
}

und dist/infra-delegated/terraform/modules/db/main.tf, das mit einem #-Kommentarblock beginnt, der den Build identifiziert, und dann die Einschränkung für den AWS-Provider, die Ressource und die Adress-Ausgabe trägt, die das Recipe veröffentlicht:

terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.69"
}
}
}
resource "aws_db_instance" "db" {
identifier = "db"
engine = "mariadb"
engine_version = "11.4"
port = 3306
## ── Compute ──────────────────────────────────────────────
instance_class = "db.t3.small"
## ── Storage ──────────────────────────────────────────────
allocated_storage = 100
storage_type = "gp3"
## ── Database ─────────────────────────────────────────────
db_name = "appdb"
username = "admin"
## Black-Box: RDS manages the password via Secrets Manager.
manage_master_user_password = true
## ── HA ───────────────────────────────────────────────────
multi_az = false
## ── Backup ───────────────────────────────────────────────
backup_retention_period = 7
## ── Provider-specific overrides ──────────────────────────
}
output "address" {
value = aws_db_instance.db.address
}

manage_master_user_password = true ist die delegierte Form, wie sie in der Ausgabe ankommt: Die Engine hält die Zugangsdaten, und das Release nennt nirgends Material. Das zugelassene Release hat ein echtes Artefakt gerendert, statt dadurch durchzukommen, dass es nichts rendert.

Die Kontroll-Richtlinie: stattdessen die Frage nach der gesamten Anbindung stellen

Tauschen Sie die angebundene Quelle in .aggrega-config.yaml aus:

sources:
- policy-attachment-wide.rego

policy-attachment-wide.rego ist derselbe Durchlauf, angesetzt an attachment.sensitive — einem einzigen booleschen Wert für die gesamte Anbindung — statt an der Liste pro Blatt:

deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
attachment.sensitive
msg := sprintf("%v: the %v credential handles sensitive material", [node_id, attachment_name])
}

Bauen Sie beide Releases neu — und stellen Sie policy.rego danach wieder her, da der Rest dieser Seite davon ausgeht. Beide werden jetzt zurückgewiesen, mit demselben Satz:

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential handles sensitive material
caused by: policy violation

Das ist kein Fehlauslösen der Regel — es ist die Regel, der eine gröbere Frage gestellt wird und die sie korrekt beantwortet. sensitive liest, was die Entitäten deklarieren: Es ist hier wahr, weil der Slot deklariert, dass alles, was ihn bindet, geheimes Material verarbeitet, und der Slot sagt das, wer auch immer ihn befüllt. Die delegierte Anbindung verfasst nichts und ist trotzdem sensibel, daher kann eine Regel, die an dieser Antwort ansetzt, die beiden Releases überhaupt nicht unterscheiden. Das delegierte Release ist ein Build, den die Regel pro Blatt zulässt und den die Regel für die gesamte Anbindung auf keine Weise zulassen kann.

Auch der dritte Fakt zur Sensibilität, sensitive_inject, hilft nicht: Er nennt Auslieferungsschlüssel, deren referenzierter Schlüssel provides als sensibel deklariert ist. Hier ist der Slot für die Auslieferung geschlossen, und das vom Autor bereitgestellte Feature veröffentlicht keine Säule provides, daher nennt er in diesem Workspace nichts. Von den drei Fakten beantwortet nur die Liste pro Blatt die Frage „Wo trägt die Payload dieser Anbindung Daten?“, und genau darum geht es in der Hausregel.

Für alle drei Fakten nebeneinander, mit den Strukturen der Payload und den Fällen, in denen jeder die richtige Frage ist, siehe die Anbindungsfakten, die eine Governance-Richtlinie liest. Zum Socket selbst — den Rollen, den Schweregraden der Verdikte, dem Eingabekanal des Betreibers — siehe den Richtlinien-Socket, und dazu, wo Richtlinien im Produkt ihren Platz haben, Governance und Compliance.

Was dieses Ziel an der verfassten Form sichtbar macht

Das Recipe der verwalteten Datenbank setzt die engine-eigene Direktive für das verwaltete Passwort bedingungslos und liest keine injizierten Zugangsdaten, daher bricht es auf diesem Ziel den Build schon an der verfassten Anbindung selbst ab und nennt dabei den Slot, statt Material anzunehmen, das nirgendwo landen kann. Die Richtlinie weist sie vorher zurück, dort, wo sie tatsächlich steht: in einer Datei, die der Workspace unter Versionskontrolle hält. Das ist das Anliegen der Governance, und es ist eine andere Sache als das, was irgendein Recipe gerendert hätte.

Deshalb sind die beiden Features auch Pendants und nicht auf jedem Ziel gleichwertige Alternativen. Binden Sie das vom Autor bereitgestellte Feature dort, wo Sie die Zugangsdaten tatsächlich besitzen, und das von der Engine verwaltete dort, wo das Ziel sie besitzt. Das verfasste Release dieses Beispiels ist die Unstimmigkeit, die eine Hausregel mechanisch erkennen kann.

Woher das Plugin kommt

Jede Entität, die dieser Workspace nutzt, stammt aus dem veröffentlichten Katalog der Standardbibliothek: die Component, die beiden Features, das Recipe, die beiden FeatureRecipes und die Governance-Plugin-Entität — gelesen aus der Hub-Registry, die .aggrega-config.yaml nennt, oder aus einem Checkout des Katalogs (wo Sie einen erhalten), der mit --catalog benannt wird.

uri: governance/rego:0.9.0 nennt diese Plugin-Entität. Es ist eine Identität: eine Koordinate <pluginType>/<name> plus eine Version, und beide Hälften gehören zur Form. Die Version ist die, unter der das Plugin veröffentlicht ist — der Hub veröffentlicht sie als oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. Die Version wirkt bei der Auflösung mit: Eine Anbindung, die eine Version nennt, die kein Katalogverzeichnis, keine Registry und auch nicht das Binary aggrega selbst führt, bricht den Build ab. Das Binary führt die Entität der Engine nur in der Version seines eigenen Release.

Mit --catalog gebaut, das einen Checkout des Katalogs benennt, braucht das Beispiel nichts weiter: Mit dem Binary aggrega der Version, die die Anbindung nennt und das die Plugin-Entität selbst enthält, wird jede Entität ohne Netzwerk aufgelöst, und die Engine, die läuft, ist die in das Binary aggrega kompilierte. Ohne diese Option werden die Entitäten von hub.aggrega.ai gelesen.

Die Rego-Engine ist in das CLI-Binary kompiliert, und ihre Version ist die Compiler-Version, mit der sie ausgeliefert wird. Ein Compiler einer anderen Version liest die Plugin-Entität, die die Anbindung nennt, vom Hub und führt die in ihn kompilierte Engine aus: Die Version in der Anbindung identifiziert die Entität und wählt nicht die Engine.

Dateien

  • aggregate-authored.yaml — der Slot root_password, im Aggregate durch core/secret-value gebunden, wobei der Auslieferungsschlüssel und das Material verfasst werden.
  • aggregate-delegated.yaml — dieselbe Datenbank ohne Anbindung: Der Entwickler bindet nichts.
  • manifest.yaml — bindet den Komponententyp und beide Feature-Typen an ihre Terraform-Recipes. Von beiden Releases gemeinsam genutzt.
  • release-negative-authored.yaml, release-delegated.yaml — eines pro Zweig, jedes mit dem directory: seiner eigenen Boundary. Es gibt kein Flag für den Ausgabeort, daher würde bei zwei Releases, die sich ein Verzeichnis teilen, das zweite das erste überschreiben. release-delegated.yaml bindet außerdem den Slot an seinem Eintrag für db mit core/generated-secret und verfasst dabei nichts. Welches Feature den Slot befüllt und in welchem Dokument, ist der einzige Unterschied zwischen den beiden Zweigen.
  • policy.rego — die Hausregel, angesetzt an der Markierung pro Blatt.
  • policy-attachment-wide.rego — die Kontrolle, angesetzt an der Antwort für die gesamte Anbindung. Standardmäßig nicht angebunden.
  • .aggrega-config.yaml — die Standard-Registry und die Governance-Anbindung.

Das Beispiel generieren

Sie können dieses Beispiel mit den folgenden Befehlen bauen oder es von Ihrem KI-Assistenten für Sie bauen lassen.

Schreiben Sie das Beispiel in einen neuen Ordner, der nach ihm benannt ist:

Terminal window
aggrega scaffold --example policy-payload-leaf-sensitivity

Danach gibt er die als Nächstes auszuführenden Befehle aus. Der erste wechselt in den neuen Ordner:

Terminal window
cd policy-payload-leaf-sensitivity

Build

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1
aggrega build --release release-delegated.yaml --auto-pull # builds

Mit einem KI-Assistenten

Ein KI-Assistent, der mit den Tools von Aggrega eingerichtet ist, kann dasselbe tun: Fügen Sie ihm diesen Prompt ein.

Verwenden Sie ausschließlich die Aggrega-Tools und legen Sie selbst keinen Ordner an. Wenn der Workspace-Ordner noch keinen Ordner `policy-payload-leaf-sensitivity` enthält, rufen Sie das Tool `scaffold` einmal auf, mit `example` auf `policy-payload-leaf-sensitivity` gesetzt und ohne `dir`: Es schreibt das Beispiel in einen neuen Ordner `policy-payload-leaf-sensitivity`. Rufen Sie dann das Tool `build` auf, mit `workspace_root` auf `policy-payload-leaf-sensitivity`, `release` auf `release-negative-authored.yaml`, `auto_pull` auf true und `write` auf true gesetzt: Dieser Build soll abgelehnt werden; lesen Sie mir also die Ablehnung vor. Rufen Sie dann das Tool `build` auf dieselbe Weise auf, mit `release` auf `release-delegated.yaml` gesetzt. Nennen Sie mir die Dateien, die dieser zweite Build geschrieben hat; sie liegen unter `policy-payload-leaf-sensitivity/dist/`.